1 /**
2 * Copyright 2014 Netflix, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
5 * compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License is
10 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
11 * the License for the specific language governing permissions and limitations under the License.
12 */
13 package rx;
14
15 import java.util.*;
16 import java.util.concurrent.*;
17
18 import rx.annotations.*;
19 import rx.exceptions.*;
20 import rx.functions.*;
21 import rx.internal.operators.*;
22 import rx.internal.util.*;
23 import rx.observables.*;
24 import rx.observers.SafeSubscriber;
25 import rx.plugins.*;
26 import rx.schedulers.*;
27 import rx.subjects.*;
28 import rx.subscriptions.Subscriptions;
29
30 /**
31 * The Observable class that implements the Reactive Pattern.
32 * <p>
33 * This class provides methods for subscribing to the Observable as well as delegate methods to the various
34 * Observers.
35 * <p>
36 * The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
37 * <p>
38 * <img width="640" height="301" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/legend.png" alt="">
39 * <p>
40 * For more information see the <a href="http://reactivex.io/documentation/observable.html">ReactiveX
41 * documentation</a>.
42 *
43 * @param <T>
44 * the type of the items emitted by the Observable
45 */
46 public class Observable<T> {
47
48 final OnSubscribe<T> onSubscribe;
49
50 /**
51 * Creates an Observable with a Function to execute when it is subscribed to.
52 * <p>
53 * <em>Note:</em> Use {@link #create(OnSubscribe)} to create an Observable, instead of this constructor,
54 * unless you specifically have a need for inheritance.
55 *
56 * @param f
57 * {@link OnSubscribe} to be executed when {@link #subscribe(Subscriber)} is called
58 */
59 protected Observable(OnSubscribe<T> f) {
60 this.onSubscribe = f;
61 }
62
63 private static final RxJavaObservableExecutionHook hook = RxJavaPlugins.getInstance().getObservableExecutionHook();
64
65 /**
66 * Returns an Observable that will execute the specified function when a {@link Subscriber} subscribes to
67 * it.
68 * <p>
69 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/create.png" alt="">
70 * <p>
71 * Write the function you pass to {@code create} so that it behaves as an Observable: It should invoke the
72 * Subscriber's {@link Subscriber#onNext onNext}, {@link Subscriber#onError onError}, and
73 * {@link Subscriber#onCompleted onCompleted} methods appropriately.
74 * <p>
75 * A well-formed Observable must invoke either the Subscriber's {@code onCompleted} method exactly once or
76 * its {@code onError} method exactly once.
77 * <p>
78 * See <a href="http://go.microsoft.com/fwlink/?LinkID=205219">Rx Design Guidelines (PDF)</a> for detailed
79 * information.
80 * <dl>
81 * <dt><b>Scheduler:</b></dt>
82 * <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>
83 * </dl>
84 *
85 * @param <T>
86 * the type of the items that this Observable emits
87 * @param f
88 * a function that accepts an {@code Subscriber<T>}, and invokes its {@code onNext},
89 * {@code onError}, and {@code onCompleted} methods as appropriate
90 * @return an Observable that, when a {@link Subscriber} subscribes to it, will execute the specified
91 * function
92 * @see <a href="http://reactivex.io/documentation/operators/create.html">ReactiveX operators documentation: Create</a>
93 */
94 public final static <T> Observable<T> create(OnSubscribe<T> f) {
95 return new Observable<T>(hook.onCreate(f));
96 }
97
98 /**
99 * Invoked when Observable.subscribe is called.
100 */
101 public interface OnSubscribe<T> extends Action1<Subscriber<? super T>> {
102 // cover for generics insanity
103 }
104
105 /**
106 * Operator function for lifting into an Observable.
107 */
108 public interface Operator<R, T> extends Func1<Subscriber<? super R>, Subscriber<? super T>> {
109 // cover for generics insanity
110 }
111
112 /**
113 * Lifts a function to the current Observable and returns a new Observable that when subscribed to will pass
114 * the values of the current Observable through the Operator function.
115 * <p>
116 * In other words, this allows chaining Observers together on an Observable for acting on the values within
117 * the Observable.
118 * <p> {@code
119 * observable.map(...).filter(...).take(5).lift(new OperatorA()).lift(new OperatorB(...)).subscribe()
120 * }
121 * <p>
122 * If the operator you are creating is designed to act on the individual items emitted by a source
123 * Observable, use {@code lift}. If your operator is designed to transform the source Observable as a whole
124 * (for instance, by applying a particular set of existing RxJava operators to it) use {@link #compose}.
125 * <dl>
126 * <dt><b>Scheduler:</b></dt>
127 * <dd>{@code lift} does not operate by default on a particular {@link Scheduler}.</dd>
128 * </dl>
129 *
130 * @param lift the Operator that implements the Observable-operating function to be applied to the source
131 * Observable
132 * @return an Observable that is the result of applying the lifted Operator to the source Observable
133 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Implementing-Your-Own-Operators">RxJava wiki: Implementing Your Own Operators</a>
134 */
135 public final <R> Observable<R> lift(final Operator<? extends R, ? super T> lift) {
136 return new Observable<R>(new OnSubscribe<R>() {
137 @Override
138 public void call(Subscriber<? super R> o) {
139 try {
140 Subscriber<? super T> st = hook.onLift(lift).call(o);
141 try {
142 // new Subscriber created and being subscribed with so 'onStart' it
143 st.onStart();
144 onSubscribe.call(st);
145 } catch (Throwable e) {
146 // localized capture of errors rather than it skipping all operators
147 // and ending up in the try/catch of the subscribe method which then
148 // prevents onErrorResumeNext and other similar approaches to error handling
149 if (e instanceof OnErrorNotImplementedException) {
150 throw (OnErrorNotImplementedException) e;
151 }
152 st.onError(e);
153 }
154 } catch (Throwable e) {
155 if (e instanceof OnErrorNotImplementedException) {
156 throw (OnErrorNotImplementedException) e;
157 }
158 // if the lift function failed all we can do is pass the error to the final Subscriber
159 // as we don't have the operator available to us
160 o.onError(e);
161 }
162 }
163 });
164 }
165
166
167 /**
168 * Transform an Observable by applying a particular Transformer function to it.
169 * <p>
170 * This method operates on the Observable itself whereas {@link #lift} operates on the Observable's
171 * Subscribers or Observers.
172 * <p>
173 * If the operator you are creating is designed to act on the individual items emitted by a source
174 * Observable, use {@link #lift}. If your operator is designed to transform the source Observable as a whole
175 * (for instance, by applying a particular set of existing RxJava operators to it) use {@code compose}.
176 * <dl>
177 * <dt><b>Scheduler:</b></dt>
178 * <dd>{@code compose} does not operate by default on a particular {@link Scheduler}.</dd>
179 * </dl>
180 *
181 * @param transformer implements the function that transforms the source Observable
182 * @return the source Observable, transformed by the transformer function
183 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Implementing-Your-Own-Operators">RxJava wiki: Implementing Your Own Operators</a>
184 */
185 @SuppressWarnings("unchecked")
186 public <R> Observable<R> compose(Transformer<? super T, ? extends R> transformer) {
187 return ((Transformer<T, R>) transformer).call(this);
188 }
189
190 /**
191 * Transformer function used by {@link #compose}.
192 * @warn more complete description needed
193 */
194 public interface Transformer<T, R> extends Func1<Observable<T>, Observable<R>> {
195 // cover for generics insanity
196 }
197
198
199
200 /* *********************************************************************************************************
201 * Operators Below Here
202 * *********************************************************************************************************
203 */
204
205 /**
206 * Mirrors the one Observable in an Iterable of several Observables that first either emits an item or sends
207 * a termination notification.
208 * <p>
209 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
210 * <dl>
211 * <dt><b>Scheduler:</b></dt>
212 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
213 * </dl>
214 *
215 * @param sources
216 * an Iterable of Observable sources competing to react first
217 * @return an Observable that emits the same sequence as whichever of the source Observables first
218 * emitted an item or sent a termination notification
219 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
220 */
221 public final static <T> Observable<T> amb(Iterable<? extends Observable<? extends T>> sources) {
222 return create(OnSubscribeAmb.amb(sources));
223 }
224
225 /**
226 * Given two Observables, mirrors the one that first either emits an item or sends a termination
227 * notification.
228 * <p>
229 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
230 * <dl>
231 * <dt><b>Scheduler:</b></dt>
232 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
233 * </dl>
234 *
235 * @param o1
236 * an Observable competing to react first
237 * @param o2
238 * an Observable competing to react first
239 * @return an Observable that emits the same sequence as whichever of the source Observables first
240 * emitted an item or sent a termination notification
241 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
242 */
243 public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2) {
244 return create(OnSubscribeAmb.amb(o1, o2));
245 }
246
247 /**
248 * Given three Observables, mirrors the one that first either emits an item or sends a termination
249 * notification.
250 * <p>
251 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
252 * <dl>
253 * <dt><b>Scheduler:</b></dt>
254 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
255 * </dl>
256 *
257 * @param o1
258 * an Observable competing to react first
259 * @param o2
260 * an Observable competing to react first
261 * @param o3
262 * an Observable competing to react first
263 * @return an Observable that emits the same sequence as whichever of the source Observables first
264 * emitted an item or sent a termination notification
265 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
266 */
267 public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3) {
268 return create(OnSubscribeAmb.amb(o1, o2, o3));
269 }
270
271 /**
272 * Given four Observables, mirrors the one that first either emits an item or sends a termination
273 * notification.
274 * <p>
275 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
276 * <dl>
277 * <dt><b>Scheduler:</b></dt>
278 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
279 * </dl>
280 *
281 * @param o1
282 * an Observable competing to react first
283 * @param o2
284 * an Observable competing to react first
285 * @param o3
286 * an Observable competing to react first
287 * @param o4
288 * an Observable competing to react first
289 * @return an Observable that emits the same sequence as whichever of the source Observables first
290 * emitted an item or sent a termination notification
291 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
292 */
293 public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4) {
294 return create(OnSubscribeAmb.amb(o1, o2, o3, o4));
295 }
296
297 /**
298 * Given five Observables, mirrors the one that first either emits an item or sends a termination
299 * notification.
300 * <p>
301 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
302 * <dl>
303 * <dt><b>Scheduler:</b></dt>
304 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
305 * </dl>
306 *
307 * @param o1
308 * an Observable competing to react first
309 * @param o2
310 * an Observable competing to react first
311 * @param o3
312 * an Observable competing to react first
313 * @param o4
314 * an Observable competing to react first
315 * @param o5
316 * an Observable competing to react first
317 * @return an Observable that emits the same sequence as whichever of the source Observables first
318 * emitted an item or sent a termination notification
319 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
320 */
321 public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5) {
322 return create(OnSubscribeAmb.amb(o1, o2, o3, o4, o5));
323 }
324
325 /**
326 * Given six Observables, mirrors the one that first either emits an item or sends a termination
327 * notification.
328 * <p>
329 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
330 * <dl>
331 * <dt><b>Scheduler:</b></dt>
332 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
333 * </dl>
334 *
335 * @param o1
336 * an Observable competing to react first
337 * @param o2
338 * an Observable competing to react first
339 * @param o3
340 * an Observable competing to react first
341 * @param o4
342 * an Observable competing to react first
343 * @param o5
344 * an Observable competing to react first
345 * @param o6
346 * an Observable competing to react first
347 * @return an Observable that emits the same sequence as whichever of the source Observables first
348 * emitted an item or sent a termination notification
349 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
350 */
351 public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5, Observable<? extends T> o6) {
352 return create(OnSubscribeAmb.amb(o1, o2, o3, o4, o5, o6));
353 }
354
355 /**
356 * Given seven Observables, mirrors the one that first either emits an item or sends a termination
357 * notification.
358 * <p>
359 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
360 * <dl>
361 * <dt><b>Scheduler:</b></dt>
362 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
363 * </dl>
364 *
365 * @param o1
366 * an Observable competing to react first
367 * @param o2
368 * an Observable competing to react first
369 * @param o3
370 * an Observable competing to react first
371 * @param o4
372 * an Observable competing to react first
373 * @param o5
374 * an Observable competing to react first
375 * @param o6
376 * an Observable competing to react first
377 * @param o7
378 * an Observable competing to react first
379 * @return an Observable that emits the same sequence as whichever of the source Observables first
380 * emitted an item or sent a termination notification
381 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
382 */
383 public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5, Observable<? extends T> o6, Observable<? extends T> o7) {
384 return create(OnSubscribeAmb.amb(o1, o2, o3, o4, o5, o6, o7));
385 }
386
387 /**
388 * Given eight Observables, mirrors the one that first either emits an item or sends a termination
389 * notification.
390 * <p>
391 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
392 * <dl>
393 * <dt><b>Scheduler:</b></dt>
394 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
395 * </dl>
396 *
397 * @param o1
398 * an Observable competing to react first
399 * @param o2
400 * an Observable competing to react first
401 * @param o3
402 * an Observable competing to react first
403 * @param o4
404 * an Observable competing to react first
405 * @param o5
406 * an Observable competing to react first
407 * @param o6
408 * an Observable competing to react first
409 * @param o7
410 * an Observable competing to react first
411 * @param o8
412 * an observable competing to react first
413 * @return an Observable that emits the same sequence as whichever of the source Observables first
414 * emitted an item or sent a termination notification
415 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
416 */
417 public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5, Observable<? extends T> o6, Observable<? extends T> o7, Observable<? extends T> o8) {
418 return create(OnSubscribeAmb.amb(o1, o2, o3, o4, o5, o6, o7, o8));
419 }
420
421 /**
422 * Given nine Observables, mirrors the one that first either emits an item or sends a termination
423 * notification.
424 * <p>
425 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
426 * <dl>
427 * <dt><b>Scheduler:</b></dt>
428 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
429 * </dl>
430 *
431 * @param o1
432 * an Observable competing to react first
433 * @param o2
434 * an Observable competing to react first
435 * @param o3
436 * an Observable competing to react first
437 * @param o4
438 * an Observable competing to react first
439 * @param o5
440 * an Observable competing to react first
441 * @param o6
442 * an Observable competing to react first
443 * @param o7
444 * an Observable competing to react first
445 * @param o8
446 * an Observable competing to react first
447 * @param o9
448 * an Observable competing to react first
449 * @return an Observable that emits the same sequence as whichever of the source Observables first
450 * emitted an item or sent a termination notification
451 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
452 */
453 public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5, Observable<? extends T> o6, Observable<? extends T> o7, Observable<? extends T> o8, Observable<? extends T> o9) {
454 return create(OnSubscribeAmb.amb(o1, o2, o3, o4, o5, o6, o7, o8, o9));
455 }
456
457 /**
458 * Combines two source Observables by emitting an item that aggregates the latest values of each of the
459 * source Observables each time an item is received from either of the source Observables, where this
460 * aggregation is defined by a specified function.
461 * <p>
462 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
463 * <dl>
464 * <dt><b>Scheduler:</b></dt>
465 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
466 * </dl>
467 *
468 * @param o1
469 * the first source Observable
470 * @param o2
471 * the second source Observable
472 * @param combineFunction
473 * the aggregation function used to combine the items emitted by the source Observables
474 * @return an Observable that emits items that are the result of combining the items emitted by the source
475 * Observables by means of the given aggregation function
476 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
477 */
478 @SuppressWarnings("unchecked")
479 public static final <T1, T2, R> Observable<R> combineLatest(Observable<? extends T1> o1, Observable<? extends T2> o2, Func2<? super T1, ? super T2, ? extends R> combineFunction) {
480 return combineLatest(Arrays.asList(o1, o2), Functions.fromFunc(combineFunction));
481 }
482
483 /**
484 * Combines three source Observables by emitting an item that aggregates the latest values of each of the
485 * source Observables each time an item is received from any of the source Observables, where this
486 * aggregation is defined by a specified function.
487 * <p>
488 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
489 * <dl>
490 * <dt><b>Scheduler:</b></dt>
491 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
492 * </dl>
493 *
494 * @param o1
495 * the first source Observable
496 * @param o2
497 * the second source Observable
498 * @param o3
499 * the third source Observable
500 * @param combineFunction
501 * the aggregation function used to combine the items emitted by the source Observables
502 * @return an Observable that emits items that are the result of combining the items emitted by the source
503 * Observables by means of the given aggregation function
504 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
505 */
506 @SuppressWarnings("unchecked")
507 public static final <T1, T2, T3, R> Observable<R> combineLatest(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Func3<? super T1, ? super T2, ? super T3, ? extends R> combineFunction) {
508 return combineLatest(Arrays.asList(o1, o2, o3), Functions.fromFunc(combineFunction));
509 }
510
511 /**
512 * Combines four source Observables by emitting an item that aggregates the latest values of each of the
513 * source Observables each time an item is received from any of the source Observables, where this
514 * aggregation is defined by a specified function.
515 * <p>
516 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
517 * <dl>
518 * <dt><b>Scheduler:</b></dt>
519 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
520 * </dl>
521 *
522 * @param o1
523 * the first source Observable
524 * @param o2
525 * the second source Observable
526 * @param o3
527 * the third source Observable
528 * @param o4
529 * the fourth source Observable
530 * @param combineFunction
531 * the aggregation function used to combine the items emitted by the source Observables
532 * @return an Observable that emits items that are the result of combining the items emitted by the source
533 * Observables by means of the given aggregation function
534 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
535 */
536 @SuppressWarnings("unchecked")
537 public static final <T1, T2, T3, T4, R> Observable<R> combineLatest(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4,
538 Func4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> combineFunction) {
539 return combineLatest(Arrays.asList(o1, o2, o3, o4), Functions.fromFunc(combineFunction));
540 }
541
542 /**
543 * Combines five source Observables by emitting an item that aggregates the latest values of each of the
544 * source Observables each time an item is received from any of the source Observables, where this
545 * aggregation is defined by a specified function.
546 * <p>
547 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
548 * <dl>
549 * <dt><b>Scheduler:</b></dt>
550 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
551 * </dl>
552 *
553 * @param o1
554 * the first source Observable
555 * @param o2
556 * the second source Observable
557 * @param o3
558 * the third source Observable
559 * @param o4
560 * the fourth source Observable
561 * @param o5
562 * the fifth source Observable
563 * @param combineFunction
564 * the aggregation function used to combine the items emitted by the source Observables
565 * @return an Observable that emits items that are the result of combining the items emitted by the source
566 * Observables by means of the given aggregation function
567 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
568 */
569 @SuppressWarnings("unchecked")
570 public static final <T1, T2, T3, T4, T5, R> Observable<R> combineLatest(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5,
571 Func5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> combineFunction) {
572 return combineLatest(Arrays.asList(o1, o2, o3, o4, o5), Functions.fromFunc(combineFunction));
573 }
574
575 /**
576 * Combines six source Observables by emitting an item that aggregates the latest values of each of the
577 * source Observables each time an item is received from any of the source Observables, where this
578 * aggregation is defined by a specified function.
579 * <p>
580 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
581 * <dl>
582 * <dt><b>Scheduler:</b></dt>
583 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
584 * </dl>
585 *
586 * @param o1
587 * the first source Observable
588 * @param o2
589 * the second source Observable
590 * @param o3
591 * the third source Observable
592 * @param o4
593 * the fourth source Observable
594 * @param o5
595 * the fifth source Observable
596 * @param o6
597 * the sixth source Observable
598 * @param combineFunction
599 * the aggregation function used to combine the items emitted by the source Observables
600 * @return an Observable that emits items that are the result of combining the items emitted by the source
601 * Observables by means of the given aggregation function
602 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
603 */
604 @SuppressWarnings("unchecked")
605 public static final <T1, T2, T3, T4, T5, T6, R> Observable<R> combineLatest(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5, Observable<? extends T6> o6,
606 Func6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> combineFunction) {
607 return combineLatest(Arrays.asList(o1, o2, o3, o4, o5, o6), Functions.fromFunc(combineFunction));
608 }
609
610 /**
611 * Combines seven source Observables by emitting an item that aggregates the latest values of each of the
612 * source Observables each time an item is received from any of the source Observables, where this
613 * aggregation is defined by a specified function.
614 * <p>
615 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
616 * <dl>
617 * <dt><b>Scheduler:</b></dt>
618 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
619 * </dl>
620 *
621 * @param o1
622 * the first source Observable
623 * @param o2
624 * the second source Observable
625 * @param o3
626 * the third source Observable
627 * @param o4
628 * the fourth source Observable
629 * @param o5
630 * the fifth source Observable
631 * @param o6
632 * the sixth source Observable
633 * @param o7
634 * the seventh source Observable
635 * @param combineFunction
636 * the aggregation function used to combine the items emitted by the source Observables
637 * @return an Observable that emits items that are the result of combining the items emitted by the source
638 * Observables by means of the given aggregation function
639 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
640 */
641 @SuppressWarnings("unchecked")
642 public static final <T1, T2, T3, T4, T5, T6, T7, R> Observable<R> combineLatest(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5, Observable<? extends T6> o6, Observable<? extends T7> o7,
643 Func7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> combineFunction) {
644 return combineLatest(Arrays.asList(o1, o2, o3, o4, o5, o6, o7), Functions.fromFunc(combineFunction));
645 }
646
647 /**
648 * Combines eight source Observables by emitting an item that aggregates the latest values of each of the
649 * source Observables each time an item is received from any of the source Observables, where this
650 * aggregation is defined by a specified function.
651 * <p>
652 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
653 * <dl>
654 * <dt><b>Scheduler:</b></dt>
655 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
656 * </dl>
657 *
658 * @param o1
659 * the first source Observable
660 * @param o2
661 * the second source Observable
662 * @param o3
663 * the third source Observable
664 * @param o4
665 * the fourth source Observable
666 * @param o5
667 * the fifth source Observable
668 * @param o6
669 * the sixth source Observable
670 * @param o7
671 * the seventh source Observable
672 * @param o8
673 * the eighth source Observable
674 * @param combineFunction
675 * the aggregation function used to combine the items emitted by the source Observables
676 * @return an Observable that emits items that are the result of combining the items emitted by the source
677 * Observables by means of the given aggregation function
678 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
679 */
680 @SuppressWarnings("unchecked")
681 public static final <T1, T2, T3, T4, T5, T6, T7, T8, R> Observable<R> combineLatest(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5, Observable<? extends T6> o6, Observable<? extends T7> o7, Observable<? extends T8> o8,
682 Func8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> combineFunction) {
683 return combineLatest(Arrays.asList(o1, o2, o3, o4, o5, o6, o7, o8), Functions.fromFunc(combineFunction));
684 }
685
686 /**
687 * Combines nine source Observables by emitting an item that aggregates the latest values of each of the
688 * source Observables each time an item is received from any of the source Observables, where this
689 * aggregation is defined by a specified function.
690 * <p>
691 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.png" alt="">
692 * <dl>
693 * <dt><b>Scheduler:</b></dt>
694 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
695 * </dl>
696 *
697 * @param o1
698 * the first source Observable
699 * @param o2
700 * the second source Observable
701 * @param o3
702 * the third source Observable
703 * @param o4
704 * the fourth source Observable
705 * @param o5
706 * the fifth source Observable
707 * @param o6
708 * the sixth source Observable
709 * @param o7
710 * the seventh source Observable
711 * @param o8
712 * the eighth source Observable
713 * @param o9
714 * the ninth source Observable
715 * @param combineFunction
716 * the aggregation function used to combine the items emitted by the source Observables
717 * @return an Observable that emits items that are the result of combining the items emitted by the source
718 * Observables by means of the given aggregation function
719 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
720 */
721 @SuppressWarnings("unchecked")
722 public static final <T1, T2, T3, T4, T5, T6, T7, T8, T9, R> Observable<R> combineLatest(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5, Observable<? extends T6> o6, Observable<? extends T7> o7, Observable<? extends T8> o8,
723 Observable<? extends T9> o9,
724 Func9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> combineFunction) {
725 return combineLatest(Arrays.asList(o1, o2, o3, o4, o5, o6, o7, o8, o9), Functions.fromFunc(combineFunction));
726 }
727 /**
728 * Combines a list of source Observables by emitting an item that aggregates the latest values of each of
729 * the source Observables each time an item is received from any of the source Observables, where this
730 * aggregation is defined by a specified function.
731 * <dl>
732 * <dt><b>Scheduler:</b></dt>
733 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
734 * </dl>
735 *
736 * @param <T>
737 * the common base type of source values
738 * @param <R>
739 * the result type
740 * @param sources
741 * the list of source Observables
742 * @param combineFunction
743 * the aggregation function used to combine the items emitted by the source Observables
744 * @return an Observable that emits items that are the result of combining the items emitted by the source
745 * Observables by means of the given aggregation function
746 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
747 */
748 public static final <T, R> Observable<R> combineLatest(List<? extends Observable<? extends T>> sources, FuncN<? extends R> combineFunction) {
749 return create(new OnSubscribeCombineLatest<T, R>(sources, combineFunction));
750 }
751
752 /**
753 * Returns an Observable that emits the items emitted by each of the Observables emitted by the source
754 * Observable, one after the other, without interleaving them.
755 * <p>
756 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
757 * <dl>
758 * <dt><b>Scheduler:</b></dt>
759 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
760 * </dl>
761 *
762 * @param observables
763 * an Observable that emits Observables
764 * @return an Observable that emits items all of the items emitted by the Observables emitted by
765 * {@code observables}, one after the other, without interleaving them
766 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
767 */
768 public final static <T> Observable<T> concat(Observable<? extends Observable<? extends T>> observables) {
769 return observables.lift(OperatorConcat.<T>instance());
770 }
771
772 /**
773 * Returns an Observable that emits the items emitted by two Observables, one after the other, without
774 * interleaving them.
775 * <p>
776 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
777 * <dl>
778 * <dt><b>Scheduler:</b></dt>
779 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
780 * </dl>
781 *
782 * @param t1
783 * an Observable to be concatenated
784 * @param t2
785 * an Observable to be concatenated
786 * @return an Observable that emits items emitted by the two source Observables, one after the other,
787 * without interleaving them
788 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
789 */
790 public final static <T> Observable<T> concat(Observable<? extends T> t1, Observable<? extends T> t2) {
791 return concat(just(t1, t2));
792 }
793
794 /**
795 * Returns an Observable that emits the items emitted by three Observables, one after the other, without
796 * interleaving them.
797 * <p>
798 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
799 * <dl>
800 * <dt><b>Scheduler:</b></dt>
801 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
802 * </dl>
803 *
804 * @param t1
805 * an Observable to be concatenated
806 * @param t2
807 * an Observable to be concatenated
808 * @param t3
809 * an Observable to be concatenated
810 * @return an Observable that emits items emitted by the three source Observables, one after the other,
811 * without interleaving them
812 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
813 */
814 public final static <T> Observable<T> concat(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3) {
815 return concat(just(t1, t2, t3));
816 }
817
818 /**
819 * Returns an Observable that emits the items emitted by four Observables, one after the other, without
820 * interleaving them.
821 * <p>
822 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
823 * <dl>
824 * <dt><b>Scheduler:</b></dt>
825 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
826 * </dl>
827 *
828 * @param t1
829 * an Observable to be concatenated
830 * @param t2
831 * an Observable to be concatenated
832 * @param t3
833 * an Observable to be concatenated
834 * @param t4
835 * an Observable to be concatenated
836 * @return an Observable that emits items emitted by the four source Observables, one after the other,
837 * without interleaving them
838 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
839 */
840 public final static <T> Observable<T> concat(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4) {
841 return concat(just(t1, t2, t3, t4));
842 }
843
844 /**
845 * Returns an Observable that emits the items emitted by five Observables, one after the other, without
846 * interleaving them.
847 * <p>
848 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
849 * <dl>
850 * <dt><b>Scheduler:</b></dt>
851 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
852 * </dl>
853 *
854 * @param t1
855 * an Observable to be concatenated
856 * @param t2
857 * an Observable to be concatenated
858 * @param t3
859 * an Observable to be concatenated
860 * @param t4
861 * an Observable to be concatenated
862 * @param t5
863 * an Observable to be concatenated
864 * @return an Observable that emits items emitted by the five source Observables, one after the other,
865 * without interleaving them
866 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
867 */
868 public final static <T> Observable<T> concat(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5) {
869 return concat(just(t1, t2, t3, t4, t5));
870 }
871
872 /**
873 * Returns an Observable that emits the items emitted by six Observables, one after the other, without
874 * interleaving them.
875 * <p>
876 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
877 * <dl>
878 * <dt><b>Scheduler:</b></dt>
879 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
880 * </dl>
881 *
882 * @param t1
883 * an Observable to be concatenated
884 * @param t2
885 * an Observable to be concatenated
886 * @param t3
887 * an Observable to be concatenated
888 * @param t4
889 * an Observable to be concatenated
890 * @param t5
891 * an Observable to be concatenated
892 * @param t6
893 * an Observable to be concatenated
894 * @return an Observable that emits items emitted by the six source Observables, one after the other,
895 * without interleaving them
896 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
897 */
898 public final static <T> Observable<T> concat(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6) {
899 return concat(just(t1, t2, t3, t4, t5, t6));
900 }
901
902 /**
903 * Returns an Observable that emits the items emitted by seven Observables, one after the other, without
904 * interleaving them.
905 * <p>
906 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
907 * <dl>
908 * <dt><b>Scheduler:</b></dt>
909 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
910 * </dl>
911 *
912 * @param t1
913 * an Observable to be concatenated
914 * @param t2
915 * an Observable to be concatenated
916 * @param t3
917 * an Observable to be concatenated
918 * @param t4
919 * an Observable to be concatenated
920 * @param t5
921 * an Observable to be concatenated
922 * @param t6
923 * an Observable to be concatenated
924 * @param t7
925 * an Observable to be concatenated
926 * @return an Observable that emits items emitted by the seven source Observables, one after the other,
927 * without interleaving them
928 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
929 */
930 public final static <T> Observable<T> concat(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6, Observable<? extends T> t7) {
931 return concat(just(t1, t2, t3, t4, t5, t6, t7));
932 }
933
934 /**
935 * Returns an Observable that emits the items emitted by eight Observables, one after the other, without
936 * interleaving them.
937 * <p>
938 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
939 * <dl>
940 * <dt><b>Scheduler:</b></dt>
941 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
942 * </dl>
943 *
944 * @param t1
945 * an Observable to be concatenated
946 * @param t2
947 * an Observable to be concatenated
948 * @param t3
949 * an Observable to be concatenated
950 * @param t4
951 * an Observable to be concatenated
952 * @param t5
953 * an Observable to be concatenated
954 * @param t6
955 * an Observable to be concatenated
956 * @param t7
957 * an Observable to be concatenated
958 * @param t8
959 * an Observable to be concatenated
960 * @return an Observable that emits items emitted by the eight source Observables, one after the other,
961 * without interleaving them
962 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
963 */
964 public final static <T> Observable<T> concat(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6, Observable<? extends T> t7, Observable<? extends T> t8) {
965 return concat(just(t1, t2, t3, t4, t5, t6, t7, t8));
966 }
967
968 /**
969 * Returns an Observable that emits the items emitted by nine Observables, one after the other, without
970 * interleaving them.
971 * <p>
972 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
973 * <dl>
974 * <dt><b>Scheduler:</b></dt>
975 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
976 * </dl>
977 *
978 * @param t1
979 * an Observable to be concatenated
980 * @param t2
981 * an Observable to be concatenated
982 * @param t3
983 * an Observable to be concatenated
984 * @param t4
985 * an Observable to be concatenated
986 * @param t5
987 * an Observable to be concatenated
988 * @param t6
989 * an Observable to be concatenated
990 * @param t7
991 * an Observable to be concatenated
992 * @param t8
993 * an Observable to be concatenated
994 * @param t9
995 * an Observable to be concatenated
996 * @return an Observable that emits items emitted by the nine source Observables, one after the other,
997 * without interleaving them
998 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
999 */
1000 public final static <T> Observable<T> concat(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6, Observable<? extends T> t7, Observable<? extends T> t8, Observable<? extends T> t9) {
1001 return concat(just(t1, t2, t3, t4, t5, t6, t7, t8, t9));
1002 }
1003
1004 /**
1005 * Returns an Observable that calls an Observable factory to create an Observable for each new Observer
1006 * that subscribes. That is, for each subscriber, the actual Observable that subscriber observes is
1007 * determined by the factory function.
1008 * <p>
1009 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/defer.png" alt="">
1010 * <p>
1011 * The defer Observer allows you to defer or delay emitting items from an Observable until such time as an
1012 * Observer subscribes to the Observable. This allows an {@link Observer} to easily obtain updates or a
1013 * refreshed version of the sequence.
1014 * <dl>
1015 * <dt><b>Scheduler:</b></dt>
1016 * <dd>{@code defer} does not operate by default on a particular {@link Scheduler}.</dd>
1017 * </dl>
1018 *
1019 * @param observableFactory
1020 * the Observable factory function to invoke for each {@link Observer} that subscribes to the
1021 * resulting Observable
1022 * @param <T>
1023 * the type of the items emitted by the Observable
1024 * @return an Observable whose {@link Observer}s' subscriptions trigger an invocation of the given
1025 * Observable factory function
1026 * @see <a href="http://reactivex.io/documentation/operators/defer.html">ReactiveX operators documentation: Defer</a>
1027 */
1028 public final static <T> Observable<T> defer(Func0<Observable<T>> observableFactory) {
1029 return create(new OnSubscribeDefer<T>(observableFactory));
1030 }
1031
1032 /** An empty observable which just emits onCompleted to any subscriber. */
1033 private static final Observable<Object> EMPTY = create(new OnSubscribe<Object>() {
1034 @Override
1035 public void call(Subscriber<? super Object> t1) {
1036 t1.onCompleted();
1037 }
1038 });
1039
1040 /**
1041 * Returns an Observable that emits no items to the {@link Observer} and immediately invokes its
1042 * {@link Observer#onCompleted onCompleted} method.
1043 * <p>
1044 * <img width="640" height="190" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/empty.png" alt="">
1045 * <dl>
1046 * <dt><b>Scheduler:</b></dt>
1047 * <dd>{@code empty} does not operate by default on a particular {@link Scheduler}.</dd>
1048 * </dl>
1049 *
1050 * @param <T>
1051 * the type of the items (ostensibly) emitted by the Observable
1052 * @return an Observable that emits no items to the {@link Observer} but immediately invokes the
1053 * {@link Observer}'s {@link Observer#onCompleted() onCompleted} method
1054 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Empty</a>
1055 */
1056 @SuppressWarnings("unchecked")
1057 public final static <T> Observable<T> empty() {
1058 return (Observable<T>)EMPTY;
1059 }
1060
1061 /**
1062 * Returns an Observable that invokes an {@link Observer}'s {@link Observer#onError onError} method when the
1063 * Observer subscribes to it.
1064 * <p>
1065 * <img width="640" height="190" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/error.png" alt="">
1066 * <dl>
1067 * <dt><b>Scheduler:</b></dt>
1068 * <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>
1069 * </dl>
1070 *
1071 * @param exception
1072 * the particular Throwable to pass to {@link Observer#onError onError}
1073 * @param <T>
1074 * the type of the items (ostensibly) emitted by the Observable
1075 * @return an Observable that invokes the {@link Observer}'s {@link Observer#onError onError} method when
1076 * the Observer subscribes to it
1077 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Throw</a>
1078 */
1079 public final static <T> Observable<T> error(Throwable exception) {
1080 return new ThrowObservable<T>(exception);
1081 }
1082
1083 /**
1084 * Converts a {@link Future} into an Observable.
1085 * <p>
1086 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.Future.png" alt="">
1087 * <p>
1088 * You can convert any object that supports the {@link Future} interface into an Observable that emits the
1089 * return value of the {@link Future#get} method of that object, by passing the object into the {@code from}
1090 * method.
1091 * <p>
1092 * <em>Important note:</em> This Observable is blocking; you cannot unsubscribe from it.
1093 * <dl>
1094 * <dt><b>Scheduler:</b></dt>
1095 * <dd>{@code from} does not operate by default on a particular {@link Scheduler}.</dd>
1096 * </dl>
1097 *
1098 * @param future
1099 * the source {@link Future}
1100 * @param <T>
1101 * the type of object that the {@link Future} returns, and also the type of item to be emitted by
1102 * the resulting Observable
1103 * @return an Observable that emits the item from the source {@link Future}
1104 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
1105 */
1106 public final static <T> Observable<T> from(Future<? extends T> future) {
1107 return create(OnSubscribeToObservableFuture.toObservableFuture(future));
1108 }
1109
1110 /**
1111 * Converts a {@link Future} into an Observable, with a timeout on the Future.
1112 * <p>
1113 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.Future.png" alt="">
1114 * <p>
1115 * You can convert any object that supports the {@link Future} interface into an Observable that emits the
1116 * return value of the {@link Future#get} method of that object, by passing the object into the {@code from}
1117 * method.
1118 * <p>
1119 * <em>Important note:</em> This Observable is blocking; you cannot unsubscribe from it.
1120 * <dl>
1121 * <dt><b>Scheduler:</b></dt>
1122 * <dd>{@code from} does not operate by default on a particular {@link Scheduler}.</dd>
1123 * </dl>
1124 *
1125 * @param future
1126 * the source {@link Future}
1127 * @param timeout
1128 * the maximum time to wait before calling {@code get}
1129 * @param unit
1130 * the {@link TimeUnit} of the {@code timeout} argument
1131 * @param <T>
1132 * the type of object that the {@link Future} returns, and also the type of item to be emitted by
1133 * the resulting Observable
1134 * @return an Observable that emits the item from the source {@link Future}
1135 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
1136 */
1137 public final static <T> Observable<T> from(Future<? extends T> future, long timeout, TimeUnit unit) {
1138 return create(OnSubscribeToObservableFuture.toObservableFuture(future, timeout, unit));
1139 }
1140
1141 /**
1142 * Converts a {@link Future}, operating on a specified {@link Scheduler}, into an Observable.
1143 * <p>
1144 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.Future.s.png" alt="">
1145 * <p>
1146 * You can convert any object that supports the {@link Future} interface into an Observable that emits the
1147 * return value of the {@link Future#get} method of that object, by passing the object into the {@code from}
1148 * method.
1149 * <dl>
1150 * <dt><b>Scheduler:</b></dt>
1151 * <dd>you specify which {@link Scheduler} this operator will use</dd>
1152 * </dl>
1153 *
1154 * @param future
1155 * the source {@link Future}
1156 * @param scheduler
1157 * the {@link Scheduler} to wait for the Future on. Use a Scheduler such as
1158 * {@link Schedulers#io()} that can block and wait on the Future
1159 * @param <T>
1160 * the type of object that the {@link Future} returns, and also the type of item to be emitted by
1161 * the resulting Observable
1162 * @return an Observable that emits the item from the source {@link Future}
1163 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
1164 */
1165 public final static <T> Observable<T> from(Future<? extends T> future, Scheduler scheduler) {
1166 // TODO in a future revision the Scheduler will become important because we'll start polling instead of blocking on the Future
1167 return create(OnSubscribeToObservableFuture.toObservableFuture(future)).subscribeOn(scheduler);
1168 }
1169
1170 /**
1171 * Converts an {@link Iterable} sequence into an Observable that emits the items in the sequence.
1172 * <p>
1173 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.png" alt="">
1174 * <dl>
1175 * <dt><b>Scheduler:</b></dt>
1176 * <dd>{@code from} does not operate by default on a particular {@link Scheduler}.</dd>
1177 * </dl>
1178 *
1179 * @param iterable
1180 * the source {@link Iterable} sequence
1181 * @param <T>
1182 * the type of items in the {@link Iterable} sequence and the type of items to be emitted by the
1183 * resulting Observable
1184 * @return an Observable that emits each item in the source {@link Iterable} sequence
1185 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
1186 */
1187 public final static <T> Observable<T> from(Iterable<? extends T> iterable) {
1188 return create(new OnSubscribeFromIterable<T>(iterable));
1189 }
1190
1191 /**
1192 * Converts an Array into an Observable that emits the items in the Array.
1193 * <p>
1194 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.png" alt="">
1195 * <dl>
1196 * <dt><b>Scheduler:</b></dt>
1197 * <dd>{@code from} does not operate by default on a particular {@link Scheduler}.</dd>
1198 * </dl>
1199 *
1200 * @param array
1201 * the source Array
1202 * @param <T>
1203 * the type of items in the Array and the type of items to be emitted by the resulting Observable
1204 * @return an Observable that emits each item in the source Array
1205 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
1206 */
1207 public final static <T> Observable<T> from(T[] array) {
1208 return from(Arrays.asList(array));
1209 }
1210
1211 /**
1212 * Returns an Observable that emits a sequential number every specified interval of time.
1213 * <p>
1214 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/interval.png" alt="">
1215 * <dl>
1216 * <dt><b>Scheduler:</b></dt>
1217 * <dd>{@code interval} operates by default on the {@code computation} {@link Scheduler}.</dd>
1218 * </dl>
1219 *
1220 * @param interval
1221 * interval size in time units (see below)
1222 * @param unit
1223 * time units to use for the interval size
1224 * @return an Observable that emits a sequential number each time interval
1225 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
1226 */
1227 public final static Observable<Long> interval(long interval, TimeUnit unit) {
1228 return interval(interval, unit, Schedulers.computation());
1229 }
1230
1231 /**
1232 * Returns an Observable that emits a sequential number every specified interval of time, on a
1233 * specified Scheduler.
1234 * <p>
1235 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/interval.s.png" alt="">
1236 * <dl>
1237 * <dt><b>Scheduler:</b></dt>
1238 * <dd>you specify which {@link Scheduler} this operator will use</dd>
1239 * </dl>
1240 *
1241 * @param interval
1242 * interval size in time units (see below)
1243 * @param unit
1244 * time units to use for the interval size
1245 * @param scheduler
1246 * the Scheduler to use for scheduling the items
1247 * @return an Observable that emits a sequential number each time interval
1248 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
1249 */
1250 public final static Observable<Long> interval(long interval, TimeUnit unit, Scheduler scheduler) {
1251 return create(new OnSubscribeTimerPeriodically(interval, interval, unit, scheduler));
1252 }
1253
1254 /**
1255 * Returns an Observable that emits a single item and then completes.
1256 * <p>
1257 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.png" alt="">
1258 * <p>
1259 * To convert any object into an Observable that emits that object, pass that object into the {@code just}
1260 * method.
1261 * <p>
1262 * This is similar to the {@link #from(java.lang.Object[])} method, except that {@code from} will convert
1263 * an {@link Iterable} object into an Observable that emits each of the items in the Iterable, one at a
1264 * time, while the {@code just} method converts an Iterable into an Observable that emits the entire
1265 * Iterable as a single item.
1266 * <dl>
1267 * <dt><b>Scheduler:</b></dt>
1268 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1269 * </dl>
1270 *
1271 * @param value
1272 * the item to emit
1273 * @param <T>
1274 * the type of that item
1275 * @return an Observable that emits {@code value} as a single item and then completes
1276 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1277 */
1278 public final static <T> Observable<T> just(final T value) {
1279 return ScalarSynchronousObservable.create(value);
1280 }
1281
1282 /**
1283 * Converts two items into an Observable that emits those items.
1284 * <p>
1285 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.png" alt="">
1286 * <dl>
1287 * <dt><b>Scheduler:</b></dt>
1288 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1289 * </dl>
1290 *
1291 * @param t1
1292 * first item
1293 * @param t2
1294 * second item
1295 * @param <T>
1296 * the type of these items
1297 * @return an Observable that emits each item
1298 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1299 */
1300 // suppress unchecked because we are using varargs inside the method
1301 @SuppressWarnings("unchecked")
1302 public final static <T> Observable<T> just(T t1, T t2) {
1303 return from(Arrays.asList(t1, t2));
1304 }
1305
1306 /**
1307 * Converts three items into an Observable that emits those items.
1308 * <p>
1309 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.png" alt="">
1310 * <dl>
1311 * <dt><b>Scheduler:</b></dt>
1312 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1313 * </dl>
1314 *
1315 * @param t1
1316 * first item
1317 * @param t2
1318 * second item
1319 * @param t3
1320 * third item
1321 * @param <T>
1322 * the type of these items
1323 * @return an Observable that emits each item
1324 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1325 */
1326 // suppress unchecked because we are using varargs inside the method
1327 @SuppressWarnings("unchecked")
1328 public final static <T> Observable<T> just(T t1, T t2, T t3) {
1329 return from(Arrays.asList(t1, t2, t3));
1330 }
1331
1332 /**
1333 * Converts four items into an Observable that emits those items.
1334 * <p>
1335 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.png" alt="">
1336 * <dl>
1337 * <dt><b>Scheduler:</b></dt>
1338 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1339 * </dl>
1340 *
1341 * @param t1
1342 * first item
1343 * @param t2
1344 * second item
1345 * @param t3
1346 * third item
1347 * @param t4
1348 * fourth item
1349 * @param <T>
1350 * the type of these items
1351 * @return an Observable that emits each item
1352 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1353 */
1354 // suppress unchecked because we are using varargs inside the method
1355 @SuppressWarnings("unchecked")
1356 public final static <T> Observable<T> just(T t1, T t2, T t3, T t4) {
1357 return from(Arrays.asList(t1, t2, t3, t4));
1358 }
1359
1360 /**
1361 * Converts five items into an Observable that emits those items.
1362 * <p>
1363 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.png" alt="">
1364 * <dl>
1365 * <dt><b>Scheduler:</b></dt>
1366 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1367 * </dl>
1368 *
1369 * @param t1
1370 * first item
1371 * @param t2
1372 * second item
1373 * @param t3
1374 * third item
1375 * @param t4
1376 * fourth item
1377 * @param t5
1378 * fifth item
1379 * @param <T>
1380 * the type of these items
1381 * @return an Observable that emits each item
1382 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1383 */
1384 // suppress unchecked because we are using varargs inside the method
1385 @SuppressWarnings("unchecked")
1386 public final static <T> Observable<T> just(T t1, T t2, T t3, T t4, T t5) {
1387 return from(Arrays.asList(t1, t2, t3, t4, t5));
1388 }
1389
1390 /**
1391 * Converts six items into an Observable that emits those items.
1392 * <p>
1393 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.png" alt="">
1394 * <dl>
1395 * <dt><b>Scheduler:</b></dt>
1396 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1397 * </dl>
1398 *
1399 * @param t1
1400 * first item
1401 * @param t2
1402 * second item
1403 * @param t3
1404 * third item
1405 * @param t4
1406 * fourth item
1407 * @param t5
1408 * fifth item
1409 * @param t6
1410 * sixth item
1411 * @param <T>
1412 * the type of these items
1413 * @return an Observable that emits each item
1414 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1415 */
1416 // suppress unchecked because we are using varargs inside the method
1417 @SuppressWarnings("unchecked")
1418 public final static <T> Observable<T> just(T t1, T t2, T t3, T t4, T t5, T t6) {
1419 return from(Arrays.asList(t1, t2, t3, t4, t5, t6));
1420 }
1421
1422 /**
1423 * Converts seven items into an Observable that emits those items.
1424 * <p>
1425 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.png" alt="">
1426 * <dl>
1427 * <dt><b>Scheduler:</b></dt>
1428 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1429 * </dl>
1430 *
1431 * @param t1
1432 * first item
1433 * @param t2
1434 * second item
1435 * @param t3
1436 * third item
1437 * @param t4
1438 * fourth item
1439 * @param t5
1440 * fifth item
1441 * @param t6
1442 * sixth item
1443 * @param t7
1444 * seventh item
1445 * @param <T>
1446 * the type of these items
1447 * @return an Observable that emits each item
1448 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1449 */
1450 // suppress unchecked because we are using varargs inside the method
1451 @SuppressWarnings("unchecked")
1452 public final static <T> Observable<T> just(T t1, T t2, T t3, T t4, T t5, T t6, T t7) {
1453 return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7));
1454 }
1455
1456 /**
1457 * Converts eight items into an Observable that emits those items.
1458 * <p>
1459 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.png" alt="">
1460 * <dl>
1461 * <dt><b>Scheduler:</b></dt>
1462 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1463 * </dl>
1464 *
1465 * @param t1
1466 * first item
1467 * @param t2
1468 * second item
1469 * @param t3
1470 * third item
1471 * @param t4
1472 * fourth item
1473 * @param t5
1474 * fifth item
1475 * @param t6
1476 * sixth item
1477 * @param t7
1478 * seventh item
1479 * @param t8
1480 * eighth item
1481 * @param <T>
1482 * the type of these items
1483 * @return an Observable that emits each item
1484 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1485 */
1486 // suppress unchecked because we are using varargs inside the method
1487 @SuppressWarnings("unchecked")
1488 public final static <T> Observable<T> just(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8) {
1489 return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8));
1490 }
1491
1492 /**
1493 * Converts nine items into an Observable that emits those items.
1494 * <p>
1495 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.png" alt="">
1496 * <dl>
1497 * <dt><b>Scheduler:</b></dt>
1498 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1499 * </dl>
1500 *
1501 * @param t1
1502 * first item
1503 * @param t2
1504 * second item
1505 * @param t3
1506 * third item
1507 * @param t4
1508 * fourth item
1509 * @param t5
1510 * fifth item
1511 * @param t6
1512 * sixth item
1513 * @param t7
1514 * seventh item
1515 * @param t8
1516 * eighth item
1517 * @param t9
1518 * ninth item
1519 * @param <T>
1520 * the type of these items
1521 * @return an Observable that emits each item
1522 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1523 */
1524 // suppress unchecked because we are using varargs inside the method
1525 @SuppressWarnings("unchecked")
1526 public final static <T> Observable<T> just(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8, T t9) {
1527 return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8, t9));
1528 }
1529
1530 /**
1531 * Converts ten items into an Observable that emits those items.
1532 * <p>
1533 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.png" alt="">
1534 * <dl>
1535 * <dt><b>Scheduler:</b></dt>
1536 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1537 * </dl>
1538 *
1539 * @param t1
1540 * first item
1541 * @param t2
1542 * second item
1543 * @param t3
1544 * third item
1545 * @param t4
1546 * fourth item
1547 * @param t5
1548 * fifth item
1549 * @param t6
1550 * sixth item
1551 * @param t7
1552 * seventh item
1553 * @param t8
1554 * eighth item
1555 * @param t9
1556 * ninth item
1557 * @param t10
1558 * tenth item
1559 * @param <T>
1560 * the type of these items
1561 * @return an Observable that emits each item
1562 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1563 */
1564 // suppress unchecked because we are using varargs inside the method
1565 @SuppressWarnings("unchecked")
1566 public final static <T> Observable<T> just(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8, T t9, T t10) {
1567 return from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10));
1568 }
1569
1570 /**
1571 * Flattens an Iterable of Observables into one Observable, without any transformation.
1572 * <p>
1573 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1574 * <p>
1575 * You can combine the items emitted by multiple Observables so that they appear as a single Observable, by
1576 * using the {@code merge} method.
1577 * <dl>
1578 * <dt><b>Scheduler:</b></dt>
1579 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1580 * </dl>
1581 *
1582 * @param sequences
1583 * the Iterable of Observables
1584 * @return an Observable that emits items that are the result of flattening the items emitted by the
1585 * Observables in the Iterable
1586 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1587 */
1588 public final static <T> Observable<T> merge(Iterable<? extends Observable<? extends T>> sequences) {
1589 return merge(from(sequences));
1590 }
1591
1592 /**
1593 * Flattens an Iterable of Observables into one Observable, without any transformation, while limiting the
1594 * number of concurrent subscriptions to these Observables.
1595 * <p>
1596 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1597 * <p>
1598 * You can combine the items emitted by multiple Observables so that they appear as a single Observable, by
1599 * using the {@code merge} method.
1600 * <dl>
1601 * <dt><b>Scheduler:</b></dt>
1602 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1603 * </dl>
1604 *
1605 * @param sequences
1606 * the Iterable of Observables
1607 * @param maxConcurrent
1608 * the maximum number of Observables that may be subscribed to concurrently
1609 * @return an Observable that emits items that are the result of flattening the items emitted by the
1610 * Observables in the Iterable
1611 * @throws IllegalArgumentException
1612 * if {@code maxConcurrent} is less than or equal to 0
1613 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1614 */
1615 public final static <T> Observable<T> merge(Iterable<? extends Observable<? extends T>> sequences, int maxConcurrent) {
1616 return merge(from(sequences), maxConcurrent);
1617 }
1618
1619 /**
1620 * Flattens an Observable that emits Observables into a single Observable that emits the items emitted by
1621 * those Observables, without any transformation.
1622 * <p>
1623 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.oo.png" alt="">
1624 * <p>
1625 * You can combine the items emitted by multiple Observables so that they appear as a single Observable, by
1626 * using the {@code merge} method.
1627 * <dl>
1628 * <dt><b>Scheduler:</b></dt>
1629 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1630 * </dl>
1631 *
1632 * @param source
1633 * an Observable that emits Observables
1634 * @return an Observable that emits items that are the result of flattening the Observables emitted by the
1635 * {@code source} Observable
1636 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1637 */
1638 public final static <T> Observable<T> merge(Observable<? extends Observable<? extends T>> source) {
1639 return source.lift(OperatorMerge.<T>instance(false));
1640 }
1641
1642 /**
1643 * Flattens an Observable that emits Observables into a single Observable that emits the items emitted by
1644 * those Observables, without any transformation, while limiting the maximum number of concurrent
1645 * subscriptions to these Observables.
1646 * <p>
1647 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.oo.png" alt="">
1648 * <p>
1649 * You can combine the items emitted by multiple Observables so that they appear as a single Observable, by
1650 * using the {@code merge} method.
1651 * <dl>
1652 * <dt><b>Scheduler:</b></dt>
1653 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1654 * </dl>
1655 *
1656 * @param source
1657 * an Observable that emits Observables
1658 * @param maxConcurrent
1659 * the maximum number of Observables that may be subscribed to concurrently
1660 * @return an Observable that emits items that are the result of flattening the Observables emitted by the
1661 * {@code source} Observable
1662 * @throws IllegalArgumentException
1663 * if {@code maxConcurrent} is less than or equal to 0
1664 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1665 */
1666 public final static <T> Observable<T> merge(Observable<? extends Observable<? extends T>> source, int maxConcurrent) {
1667 return source.lift(new OperatorMergeMaxConcurrent<T>(maxConcurrent));
1668 }
1669
1670 /**
1671 * Flattens two Observables into a single Observable, without any transformation.
1672 * <p>
1673 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1674 * <p>
1675 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
1676 * using the {@code merge} method.
1677 * <dl>
1678 * <dt><b>Scheduler:</b></dt>
1679 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1680 * </dl>
1681 *
1682 * @param t1
1683 * an Observable to be merged
1684 * @param t2
1685 * an Observable to be merged
1686 * @return an Observable that emits all of the items emitted by the source Observables
1687 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1688 */
1689 @SuppressWarnings("unchecked")
1690 public final static <T> Observable<T> merge(Observable<? extends T> t1, Observable<? extends T> t2) {
1691 return merge(from(Arrays.asList(t1, t2)));
1692 }
1693
1694 /**
1695 * Flattens three Observables into a single Observable, without any transformation.
1696 * <p>
1697 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1698 * <p>
1699 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
1700 * using the {@code merge} method.
1701 * <dl>
1702 * <dt><b>Scheduler:</b></dt>
1703 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1704 * </dl>
1705 *
1706 * @param t1
1707 * an Observable to be merged
1708 * @param t2
1709 * an Observable to be merged
1710 * @param t3
1711 * an Observable to be merged
1712 * @return an Observable that emits all of the items emitted by the source Observables
1713 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1714 */
1715 @SuppressWarnings("unchecked")
1716 public final static <T> Observable<T> merge(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3) {
1717 return merge(from(Arrays.asList(t1, t2, t3)));
1718 }
1719
1720 /**
1721 * Flattens four Observables into a single Observable, without any transformation.
1722 * <p>
1723 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1724 * <p>
1725 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
1726 * using the {@code merge} method.
1727 * <dl>
1728 * <dt><b>Scheduler:</b></dt>
1729 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1730 * </dl>
1731 *
1732 * @param t1
1733 * an Observable to be merged
1734 * @param t2
1735 * an Observable to be merged
1736 * @param t3
1737 * an Observable to be merged
1738 * @param t4
1739 * an Observable to be merged
1740 * @return an Observable that emits all of the items emitted by the source Observables
1741 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1742 */
1743 @SuppressWarnings("unchecked")
1744 public final static <T> Observable<T> merge(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4) {
1745 return merge(from(Arrays.asList(t1, t2, t3, t4)));
1746 }
1747
1748 /**
1749 * Flattens five Observables into a single Observable, without any transformation.
1750 * <p>
1751 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1752 * <p>
1753 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
1754 * using the {@code merge} method.
1755 * <dl>
1756 * <dt><b>Scheduler:</b></dt>
1757 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1758 * </dl>
1759 *
1760 * @param t1
1761 * an Observable to be merged
1762 * @param t2
1763 * an Observable to be merged
1764 * @param t3
1765 * an Observable to be merged
1766 * @param t4
1767 * an Observable to be merged
1768 * @param t5
1769 * an Observable to be merged
1770 * @return an Observable that emits all of the items emitted by the source Observables
1771 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1772 */
1773 @SuppressWarnings("unchecked")
1774 public final static <T> Observable<T> merge(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5) {
1775 return merge(from(Arrays.asList(t1, t2, t3, t4, t5)));
1776 }
1777
1778 /**
1779 * Flattens six Observables into a single Observable, without any transformation.
1780 * <p>
1781 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1782 * <p>
1783 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
1784 * using the {@code merge} method.
1785 * <dl>
1786 * <dt><b>Scheduler:</b></dt>
1787 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1788 * </dl>
1789 *
1790 * @param t1
1791 * an Observable to be merged
1792 * @param t2
1793 * an Observable to be merged
1794 * @param t3
1795 * an Observable to be merged
1796 * @param t4
1797 * an Observable to be merged
1798 * @param t5
1799 * an Observable to be merged
1800 * @param t6
1801 * an Observable to be merged
1802 * @return an Observable that emits all of the items emitted by the source Observables
1803 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1804 */
1805 @SuppressWarnings("unchecked")
1806 public final static <T> Observable<T> merge(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6) {
1807 return merge(from(Arrays.asList(t1, t2, t3, t4, t5, t6)));
1808 }
1809
1810 /**
1811 * Flattens seven Observables into a single Observable, without any transformation.
1812 * <p>
1813 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1814 * <p>
1815 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
1816 * using the {@code merge} method.
1817 * <dl>
1818 * <dt><b>Scheduler:</b></dt>
1819 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1820 * </dl>
1821 *
1822 * @param t1
1823 * an Observable to be merged
1824 * @param t2
1825 * an Observable to be merged
1826 * @param t3
1827 * an Observable to be merged
1828 * @param t4
1829 * an Observable to be merged
1830 * @param t5
1831 * an Observable to be merged
1832 * @param t6
1833 * an Observable to be merged
1834 * @param t7
1835 * an Observable to be merged
1836 * @return an Observable that emits all of the items emitted by the source Observables
1837 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1838 */
1839 @SuppressWarnings("unchecked")
1840 public final static <T> Observable<T> merge(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6, Observable<? extends T> t7) {
1841 return merge(from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7)));
1842 }
1843
1844 /**
1845 * Flattens eight Observables into a single Observable, without any transformation.
1846 * <p>
1847 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1848 * <p>
1849 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
1850 * using the {@code merge} method.
1851 * <dl>
1852 * <dt><b>Scheduler:</b></dt>
1853 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1854 * </dl>
1855 *
1856 * @param t1
1857 * an Observable to be merged
1858 * @param t2
1859 * an Observable to be merged
1860 * @param t3
1861 * an Observable to be merged
1862 * @param t4
1863 * an Observable to be merged
1864 * @param t5
1865 * an Observable to be merged
1866 * @param t6
1867 * an Observable to be merged
1868 * @param t7
1869 * an Observable to be merged
1870 * @param t8
1871 * an Observable to be merged
1872 * @return an Observable that emits all of the items emitted by the source Observables
1873 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1874 */
1875 @SuppressWarnings("unchecked")
1876 public final static <T> Observable<T> merge(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6, Observable<? extends T> t7, Observable<? extends T> t8) {
1877 return merge(from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8)));
1878 }
1879
1880 /**
1881 * Flattens nine Observables into a single Observable, without any transformation.
1882 * <p>
1883 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
1884 * <p>
1885 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
1886 * using the {@code merge} method.
1887 * <dl>
1888 * <dt><b>Scheduler:</b></dt>
1889 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1890 * </dl>
1891 *
1892 * @param t1
1893 * an Observable to be merged
1894 * @param t2
1895 * an Observable to be merged
1896 * @param t3
1897 * an Observable to be merged
1898 * @param t4
1899 * an Observable to be merged
1900 * @param t5
1901 * an Observable to be merged
1902 * @param t6
1903 * an Observable to be merged
1904 * @param t7
1905 * an Observable to be merged
1906 * @param t8
1907 * an Observable to be merged
1908 * @param t9
1909 * an Observable to be merged
1910 * @return an Observable that emits all of the items emitted by the source Observables
1911 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1912 */
1913 @SuppressWarnings("unchecked")
1914 public final static <T> Observable<T> merge(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6, Observable<? extends T> t7, Observable<? extends T> t8, Observable<? extends T> t9) {
1915 return merge(from(Arrays.asList(t1, t2, t3, t4, t5, t6, t7, t8, t9)));
1916 }
1917
1918 /**
1919 * Flattens an Array of Observables into one Observable, without any transformation.
1920 * <p>
1921 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.io.png" alt="">
1922 * <p>
1923 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
1924 * using the {@code merge} method.
1925 * <dl>
1926 * <dt><b>Scheduler:</b></dt>
1927 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1928 * </dl>
1929 *
1930 * @param sequences
1931 * the Array of Observables
1932 * @return an Observable that emits all of the items emitted by the Observables in the Array
1933 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1934 */
1935 public final static <T> Observable<T> merge(Observable<? extends T>[] sequences) {
1936 return merge(from(sequences));
1937 }
1938
1939 /**
1940 * Flattens an Observable that emits Observables into one Observable, in a way that allows an Observer to
1941 * receive all successfully emitted items from all of the source Observables without being interrupted by
1942 * an error notification from one of them.
1943 * <p>
1944 * This behaves like {@link #merge(Observable)} except that if any of the merged Observables notify of an
1945 * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that
1946 * error notification until all of the merged Observables have finished emitting items.
1947 * <p>
1948 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.png" alt="">
1949 * <p>
1950 * Even if multiple merged Observables send {@code onError} notifications, {@code mergeDelayError} will only
1951 * invoke the {@code onError} method of its Observers once.
1952 * <dl>
1953 * <dt><b>Scheduler:</b></dt>
1954 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1955 * </dl>
1956 *
1957 * @param source
1958 * an Observable that emits Observables
1959 * @return an Observable that emits all of the items emitted by the Observables emitted by the
1960 * {@code source} Observable
1961 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1962 */
1963 public final static <T> Observable<T> mergeDelayError(Observable<? extends Observable<? extends T>> source) {
1964 return source.lift(OperatorMerge.<T>instance(true));
1965 }
1966
1967 /**
1968 * Flattens two Observables into one Observable, in a way that allows an Observer to receive all
1969 * successfully emitted items from each of the source Observables without being interrupted by an error
1970 * notification from one of them.
1971 * <p>
1972 * This behaves like {@link #merge(Observable, Observable)} except that if any of the merged Observables
1973 * notify of an error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from
1974 * propagating that error notification until all of the merged Observables have finished emitting items.
1975 * <p>
1976 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.png" alt="">
1977 * <p>
1978 * Even if both merged Observables send {@code onError} notifications, {@code mergeDelayError} will only
1979 * invoke the {@code onError} method of its Observers once.
1980 * <dl>
1981 * <dt><b>Scheduler:</b></dt>
1982 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1983 * </dl>
1984 *
1985 * @param t1
1986 * an Observable to be merged
1987 * @param t2
1988 * an Observable to be merged
1989 * @return an Observable that emits all of the items that are emitted by the two source Observables
1990 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1991 */
1992 public final static <T> Observable<T> mergeDelayError(Observable<? extends T> t1, Observable<? extends T> t2) {
1993 return mergeDelayError(just(t1, t2));
1994 }
1995
1996 /**
1997 * Flattens three Observables into one Observable, in a way that allows an Observer to receive all
1998 * successfully emitted items from all of the source Observables without being interrupted by an error
1999 * notification from one of them.
2000 * <p>
2001 * This behaves like {@link #merge(Observable, Observable, Observable)} except that if any of the merged
2002 * Observables notify of an error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain
2003 * from propagating that error notification until all of the merged Observables have finished emitting
2004 * items.
2005 * <p>
2006 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.png" alt="">
2007 * <p>
2008 * Even if multiple merged Observables send {@code onError} notifications, {@code mergeDelayError} will only
2009 * invoke the {@code onError} method of its Observers once.
2010 * <dl>
2011 * <dt><b>Scheduler:</b></dt>
2012 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
2013 * </dl>
2014 *
2015 * @param t1
2016 * an Observable to be merged
2017 * @param t2
2018 * an Observable to be merged
2019 * @param t3
2020 * an Observable to be merged
2021 * @return an Observable that emits all of the items that are emitted by the source Observables
2022 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
2023 */
2024 public final static <T> Observable<T> mergeDelayError(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3) {
2025 return mergeDelayError(just(t1, t2, t3));
2026 }
2027
2028 /**
2029 * Flattens four Observables into one Observable, in a way that allows an Observer to receive all
2030 * successfully emitted items from all of the source Observables without being interrupted by an error
2031 * notification from one of them.
2032 * <p>
2033 * This behaves like {@link #merge(Observable, Observable, Observable, Observable)} except that if any of
2034 * the merged Observables notify of an error via {@link Observer#onError onError}, {@code mergeDelayError}
2035 * will refrain from propagating that error notification until all of the merged Observables have finished
2036 * emitting items.
2037 * <p>
2038 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.png" alt="">
2039 * <p>
2040 * Even if multiple merged Observables send {@code onError} notifications, {@code mergeDelayError} will only
2041 * invoke the {@code onError} method of its Observers once.
2042 * <dl>
2043 * <dt><b>Scheduler:</b></dt>
2044 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
2045 * </dl>
2046 *
2047 * @param t1
2048 * an Observable to be merged
2049 * @param t2
2050 * an Observable to be merged
2051 * @param t3
2052 * an Observable to be merged
2053 * @param t4
2054 * an Observable to be merged
2055 * @return an Observable that emits all of the items that are emitted by the source Observables
2056 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
2057 */
2058 public final static <T> Observable<T> mergeDelayError(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4) {
2059 return mergeDelayError(just(t1, t2, t3, t4));
2060 }
2061
2062 /**
2063 * Flattens five Observables into one Observable, in a way that allows an Observer to receive all
2064 * successfully emitted items from all of the source Observables without being interrupted by an error
2065 * notification from one of them.
2066 * <p>
2067 * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable)} except that
2068 * if any of the merged Observables notify of an error via {@link Observer#onError onError},
2069 * {@code mergeDelayError} will refrain from propagating that error notification until all of the merged
2070 * Observables have finished emitting items.
2071 * <p>
2072 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.png" alt="">
2073 * <p>
2074 * Even if multiple merged Observables send {@code onError} notifications, {@code mergeDelayError} will only
2075 * invoke the {@code onError} method of its Observers once.
2076 * <dl>
2077 * <dt><b>Scheduler:</b></dt>
2078 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
2079 * </dl>
2080 *
2081 * @param t1
2082 * an Observable to be merged
2083 * @param t2
2084 * an Observable to be merged
2085 * @param t3
2086 * an Observable to be merged
2087 * @param t4
2088 * an Observable to be merged
2089 * @param t5
2090 * an Observable to be merged
2091 * @return an Observable that emits all of the items that are emitted by the source Observables
2092 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
2093 */
2094 public final static <T> Observable<T> mergeDelayError(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5) {
2095 return mergeDelayError(just(t1, t2, t3, t4, t5));
2096 }
2097
2098 /**
2099 * Flattens six Observables into one Observable, in a way that allows an Observer to receive all
2100 * successfully emitted items from all of the source Observables without being interrupted by an error
2101 * notification from one of them.
2102 * <p>
2103 * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable)}
2104 * except that if any of the merged Observables notify of an error via {@link Observer#onError onError},
2105 * {@code mergeDelayError} will refrain from propagating that error notification until all of the merged
2106 * Observables have finished emitting items.
2107 * <p>
2108 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.png" alt="">
2109 * <p>
2110 * Even if multiple merged Observables send {@code onError} notifications, {@code mergeDelayError} will only
2111 * invoke the {@code onError} method of its Observers once.
2112 * <dl>
2113 * <dt><b>Scheduler:</b></dt>
2114 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
2115 * </dl>
2116 *
2117 * @param t1
2118 * an Observable to be merged
2119 * @param t2
2120 * an Observable to be merged
2121 * @param t3
2122 * an Observable to be merged
2123 * @param t4
2124 * an Observable to be merged
2125 * @param t5
2126 * an Observable to be merged
2127 * @param t6
2128 * an Observable to be merged
2129 * @return an Observable that emits all of the items that are emitted by the source Observables
2130 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
2131 */
2132 public final static <T> Observable<T> mergeDelayError(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6) {
2133 return mergeDelayError(just(t1, t2, t3, t4, t5, t6));
2134 }
2135
2136 /**
2137 * Flattens seven Observables into one Observable, in a way that allows an Observer to receive all
2138 * successfully emitted items from all of the source Observables without being interrupted by an error
2139 * notification from one of them.
2140 * <p>
2141 * This behaves like
2142 * {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable, Observable)}
2143 * except that if any of the merged Observables notify of an error via {@link Observer#onError onError},
2144 * {@code mergeDelayError} will refrain from propagating that error notification until all of the merged
2145 * Observables have finished emitting items.
2146 * <p>
2147 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.png" alt="">
2148 * <p>
2149 * Even if multiple merged Observables send {@code onError} notifications, {@code mergeDelayError} will only
2150 * invoke the {@code onError} method of its Observers once.
2151 * <dl>
2152 * <dt><b>Scheduler:</b></dt>
2153 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
2154 * </dl>
2155 *
2156 * @param t1
2157 * an Observable to be merged
2158 * @param t2
2159 * an Observable to be merged
2160 * @param t3
2161 * an Observable to be merged
2162 * @param t4
2163 * an Observable to be merged
2164 * @param t5
2165 * an Observable to be merged
2166 * @param t6
2167 * an Observable to be merged
2168 * @param t7
2169 * an Observable to be merged
2170 * @return an Observable that emits all of the items that are emitted by the source Observables
2171 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
2172 */
2173 public final static <T> Observable<T> mergeDelayError(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6, Observable<? extends T> t7) {
2174 return mergeDelayError(just(t1, t2, t3, t4, t5, t6, t7));
2175 }
2176
2177 /**
2178 * Flattens eight Observables into one Observable, in a way that allows an Observer to receive all
2179 * successfully emitted items from all of the source Observables without being interrupted by an error
2180 * notification from one of them.
2181 * <p>
2182 * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable, Observable, Observable)}
2183 * except that if any of the merged Observables notify of an error via {@link Observer#onError onError},
2184 * {@code mergeDelayError} will refrain from propagating that error notification until all of the merged
2185 * Observables have finished emitting items.
2186 * <p>
2187 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.png" alt="">
2188 * <p>
2189 * Even if multiple merged Observables send {@code onError} notifications, {@code mergeDelayError} will only
2190 * invoke the {@code onError} method of its Observers once.
2191 * <dl>
2192 * <dt><b>Scheduler:</b></dt>
2193 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
2194 * </dl>
2195 *
2196 * @param t1
2197 * an Observable to be merged
2198 * @param t2
2199 * an Observable to be merged
2200 * @param t3
2201 * an Observable to be merged
2202 * @param t4
2203 * an Observable to be merged
2204 * @param t5
2205 * an Observable to be merged
2206 * @param t6
2207 * an Observable to be merged
2208 * @param t7
2209 * an Observable to be merged
2210 * @param t8
2211 * an Observable to be merged
2212 * @return an Observable that emits all of the items that are emitted by the source Observables
2213 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
2214 */
2215 // suppress because the types are checked by the method signature before using a vararg
2216 public final static <T> Observable<T> mergeDelayError(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6, Observable<? extends T> t7, Observable<? extends T> t8) {
2217 return mergeDelayError(just(t1, t2, t3, t4, t5, t6, t7, t8));
2218 }
2219
2220 /**
2221 * Flattens nine Observables into one Observable, in a way that allows an Observer to receive all
2222 * successfully emitted items from all of the source Observables without being interrupted by an error
2223 * notification from one of them.
2224 * <p>
2225 * This behaves like {@link #merge(Observable, Observable, Observable, Observable, Observable, Observable, Observable, Observable, Observable)}
2226 * except that if any of the merged Observables notify of an error via {@link Observer#onError onError},
2227 * {@code mergeDelayError} will refrain from propagating that error notification until all of the merged
2228 * Observables have finished emitting items.
2229 * <p>
2230 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.png" alt="">
2231 * <p>
2232 * Even if multiple merged Observables send {@code onError} notifications, {@code mergeDelayError} will only
2233 * invoke the {@code onError} method of its Observers once.
2234 * <dl>
2235 * <dt><b>Scheduler:</b></dt>
2236 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
2237 * </dl>
2238 *
2239 * @param t1
2240 * an Observable to be merged
2241 * @param t2
2242 * an Observable to be merged
2243 * @param t3
2244 * an Observable to be merged
2245 * @param t4
2246 * an Observable to be merged
2247 * @param t5
2248 * an Observable to be merged
2249 * @param t6
2250 * an Observable to be merged
2251 * @param t7
2252 * an Observable to be merged
2253 * @param t8
2254 * an Observable to be merged
2255 * @param t9
2256 * an Observable to be merged
2257 * @return an Observable that emits all of the items that are emitted by the source Observables
2258 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
2259 */
2260 public final static <T> Observable<T> mergeDelayError(Observable<? extends T> t1, Observable<? extends T> t2, Observable<? extends T> t3, Observable<? extends T> t4, Observable<? extends T> t5, Observable<? extends T> t6, Observable<? extends T> t7, Observable<? extends T> t8, Observable<? extends T> t9) {
2261 return mergeDelayError(just(t1, t2, t3, t4, t5, t6, t7, t8, t9));
2262 }
2263
2264 /**
2265 * Converts the source {@code Observable<T>} into an {@code Observable<Observable<T>>} that emits the
2266 * source Observable as its single emission.
2267 * <p>
2268 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/nest.png" alt="">
2269 * <dl>
2270 * <dt><b>Scheduler:</b></dt>
2271 * <dd>{@code nest} does not operate by default on a particular {@link Scheduler}.</dd>
2272 * </dl>
2273 *
2274 * @return an Observable that emits a single item: the source Observable
2275 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
2276 */
2277 public final Observable<Observable<T>> nest() {
2278 return just(this);
2279 }
2280
2281 /**
2282 * Returns an Observable that never sends any items or notifications to an {@link Observer}.
2283 * <p>
2284 * <img width="640" height="185" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/never.png" alt="">
2285 * <p>
2286 * This Observable is useful primarily for testing purposes.
2287 * <dl>
2288 * <dt><b>Scheduler:</b></dt>
2289 * <dd>{@code never} does not operate by default on a particular {@link Scheduler}.</dd>
2290 * </dl>
2291 *
2292 * @param <T>
2293 * the type of items (not) emitted by the Observable
2294 * @return an Observable that never emits any items or sends any notifications to an {@link Observer}
2295 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Never</a>
2296 */
2297 public final static <T> Observable<T> never() {
2298 return new NeverObservable<T>();
2299 }
2300
2301 /**
2302 * Returns an Observable that emits a sequence of Integers within a specified range.
2303 * <p>
2304 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/range.png" alt="">
2305 * <dl>
2306 * <dt><b>Scheduler:</b></dt>
2307 * <dd>{@code range} does not operate by default on a particular {@link Scheduler}.</dd>
2308 * </dl>
2309 *
2310 * @param start
2311 * the value of the first Integer in the sequence
2312 * @param count
2313 * the number of sequential Integers to generate
2314 * @return an Observable that emits a range of sequential Integers
2315 * @throws IllegalArgumentException
2316 * if {@code count} is less than zero, or if {@code start} + {@code count} − 1 exceeds
2317 * {@code Integer.MAX_VALUE}
2318 * @see <a href="http://reactivex.io/documentation/operators/range.html">ReactiveX operators documentation: Range</a>
2319 */
2320 public final static Observable<Integer> range(int start, int count) {
2321 if (count < 0) {
2322 throw new IllegalArgumentException("Count can not be negative");
2323 }
2324 if (count == 0) {
2325 return Observable.empty();
2326 }
2327 if (start > Integer.MAX_VALUE - count + 1) {
2328 throw new IllegalArgumentException("start + count can not exceed Integer.MAX_VALUE");
2329 }
2330 if(count == 1) {
2331 return Observable.just(start);
2332 }
2333 return Observable.create(new OnSubscribeRange(start, start + (count - 1)));
2334 }
2335
2336 /**
2337 * Returns an Observable that emits a sequence of Integers within a specified range, on a specified
2338 * Scheduler.
2339 * <p>
2340 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/range.s.png" alt="">
2341 * <dl>
2342 * <dt><b>Scheduler:</b></dt>
2343 * <dd>you specify which {@link Scheduler} this operator will use</dd>
2344 * </dl>
2345 *
2346 * @param start
2347 * the value of the first Integer in the sequence
2348 * @param count
2349 * the number of sequential Integers to generate
2350 * @param scheduler
2351 * the Scheduler to run the generator loop on
2352 * @return an Observable that emits a range of sequential Integers
2353 * @see <a href="http://reactivex.io/documentation/operators/range.html">ReactiveX operators documentation: Range</a>
2354 */
2355 public final static Observable<Integer> range(int start, int count, Scheduler scheduler) {
2356 return range(start, count).subscribeOn(scheduler);
2357 }
2358
2359 /**
2360 * Returns an Observable that emits a Boolean value that indicates whether two Observable sequences are the
2361 * same by comparing the items emitted by each Observable pairwise.
2362 * <p>
2363 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.png" alt="">
2364 * <dl>
2365 * <dt><b>Scheduler:</b></dt>
2366 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
2367 * </dl>
2368 *
2369 * @param first
2370 * the first Observable to compare
2371 * @param second
2372 * the second Observable to compare
2373 * @param <T>
2374 * the type of items emitted by each Observable
2375 * @return an Observable that emits a Boolean value that indicates whether the two sequences are the same
2376 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
2377 */
2378 public final static <T> Observable<Boolean> sequenceEqual(Observable<? extends T> first, Observable<? extends T> second) {
2379 return sequenceEqual(first, second, new Func2<T, T, Boolean>() {
2380 @Override
2381 public final Boolean call(T first, T second) {
2382 if (first == null) {
2383 return second == null;
2384 }
2385 return first.equals(second);
2386 }
2387 });
2388 }
2389
2390 /**
2391 * Returns an Observable that emits a Boolean value that indicates whether two Observable sequences are the
2392 * same by comparing the items emitted by each Observable pairwise based on the results of a specified
2393 * equality function.
2394 * <p>
2395 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.png" alt="">
2396 * <dl>
2397 * <dt><b>Scheduler:</b></dt>
2398 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
2399 * </dl>
2400 *
2401 * @param first
2402 * the first Observable to compare
2403 * @param second
2404 * the second Observable to compare
2405 * @param equality
2406 * a function used to compare items emitted by each Observable
2407 * @param <T>
2408 * the type of items emitted by each Observable
2409 * @return an Observable that emits a Boolean value that indicates whether the two Observable two sequences
2410 * are the same according to the specified function
2411 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
2412 */
2413 public final static <T> Observable<Boolean> sequenceEqual(Observable<? extends T> first, Observable<? extends T> second, Func2<? super T, ? super T, Boolean> equality) {
2414 return OperatorSequenceEqual.sequenceEqual(first, second, equality);
2415 }
2416
2417 /**
2418 * Converts an Observable that emits Observables into an Observable that emits the items emitted by the
2419 * most recently emitted of those Observables.
2420 * <p>
2421 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchDo.png" alt="">
2422 * <p>
2423 * {@code switchOnNext} subscribes to an Observable that emits Observables. Each time it observes one of
2424 * these emitted Observables, the Observable returned by {@code switchOnNext} begins emitting the items
2425 * emitted by that Observable. When a new Observable is emitted, {@code switchOnNext} stops emitting items
2426 * from the earlier-emitted Observable and begins emitting items from the new one.
2427 * <dl>
2428 * <dt><b>Scheduler:</b></dt>
2429 * <dd>{@code switchOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
2430 * </dl>
2431 *
2432 * @param <T> the item type
2433 * @param sequenceOfSequences
2434 * the source Observable that emits Observables
2435 * @return an Observable that emits the items emitted by the Observable most recently emitted by the source
2436 * Observable
2437 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
2438 */
2439 public final static <T> Observable<T> switchOnNext(Observable<? extends Observable<? extends T>> sequenceOfSequences) {
2440 return sequenceOfSequences.lift(OperatorSwitch.<T>instance());
2441 }
2442
2443 /**
2444 * Returns an Observable that emits a {@code 0L} after the {@code initialDelay} and ever increasing numbers
2445 * after each {@code period} of time thereafter.
2446 * <p>
2447 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.p.png" alt="">
2448 * <dl>
2449 * <dt><b>Backpressure Support:</b></dt>
2450 * <dd>This operator does not support backpressure as it uses time. If the downstream needs a slower rate
2451 * it should slow the timer or use something like {@link #onBackpressureDrop}.</dd>
2452 * <dt><b>Scheduler:</b></dt>
2453 * <dd>{@code timer} operates by default on the {@code computation} {@link Scheduler}.</dd>
2454 * </dl>
2455 *
2456 * @param initialDelay
2457 * the initial delay time to wait before emitting the first value of 0L
2458 * @param period
2459 * the period of time between emissions of the subsequent numbers
2460 * @param unit
2461 * the time unit for both {@code initialDelay} and {@code period}
2462 * @return an Observable that emits a 0L after the {@code initialDelay} and ever increasing numbers after
2463 * each {@code period} of time thereafter
2464 * @see <a href="http://reactivex.io/documentation/operators/timer.html">ReactiveX operators documentation: Timer</a>
2465 */
2466 public final static Observable<Long> timer(long initialDelay, long period, TimeUnit unit) {
2467 return timer(initialDelay, period, unit, Schedulers.computation());
2468 }
2469
2470 /**
2471 * Returns an Observable that emits a {@code 0L} after the {@code initialDelay} and ever increasing numbers
2472 * after each {@code period} of time thereafter, on a specified {@link Scheduler}.
2473 * <p>
2474 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.ps.png" alt="">
2475 * <dl>
2476 * <dt><b>Backpressure Support:</b></dt>
2477 * <dd>This operator does not support backpressure as it uses time. If the downstream needs a slower rate
2478 * it should slow the timer or use something like {@link #onBackpressureDrop}.</dd>
2479 * <dt><b>Scheduler:</b></dt>
2480 * <dd>you specify which {@link Scheduler} this operator will use</dd>
2481 * </dl>
2482 *
2483 * @param initialDelay
2484 * the initial delay time to wait before emitting the first value of 0L
2485 * @param period
2486 * the period of time between emissions of the subsequent numbers
2487 * @param unit
2488 * the time unit for both {@code initialDelay} and {@code period}
2489 * @param scheduler
2490 * the Scheduler on which the waiting happens and items are emitted
2491 * @return an Observable that emits a 0L after the {@code initialDelay} and ever increasing numbers after
2492 * each {@code period} of time thereafter, while running on the given Scheduler
2493 * @see <a href="http://reactivex.io/documentation/operators/timer.html">ReactiveX operators documentation: Timer</a>
2494 */
2495 public final static Observable<Long> timer(long initialDelay, long period, TimeUnit unit, Scheduler scheduler) {
2496 return create(new OnSubscribeTimerPeriodically(initialDelay, period, unit, scheduler));
2497 }
2498
2499 /**
2500 * Returns an Observable that emits one item after a specified delay, and then completes.
2501 * <p>
2502 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.png" alt="">
2503 * <dl>
2504 * <dt><b>Backpressure Support:</b></dt>
2505 * <dd>This operator does not support backpressure as it uses time. If the downstream needs a slower rate
2506 * it should slow the timer or use something like {@link #onBackpressureDrop}.</dd>
2507 * <dt><b>Scheduler:</b></dt>
2508 * <dd>{@code timer} operates by default on the {@code computation} {@link Scheduler}.</dd>
2509 * </dl>
2510 *
2511 * @param delay
2512 * the initial delay before emitting a single {@code 0L}
2513 * @param unit
2514 * time units to use for {@code delay}
2515 * @return an Observable that emits one item after a specified delay, and then completes
2516 * @see <a href="http://reactivex.io/documentation/operators/timer.html">ReactiveX operators documentation: Timer</a>
2517 */
2518 public final static Observable<Long> timer(long delay, TimeUnit unit) {
2519 return timer(delay, unit, Schedulers.computation());
2520 }
2521
2522 /**
2523 * Returns an Observable that emits one item after a specified delay, on a specified Scheduler, and then
2524 * completes.
2525 * <p>
2526 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.s.png" alt="">
2527 * <dl>
2528 * <dt><b>Backpressure Support:</b></dt>
2529 * <dd>This operator does not support backpressure as it uses time. If the downstream needs a slower rate
2530 * it should slow the timer or use something like {@link #onBackpressureDrop}.</dd>
2531 * <dt><b>Scheduler:</b></dt>
2532 * <dd>you specify which {@link Scheduler} this operator will use</dd>
2533 * </dl>
2534 *
2535 * @param delay
2536 * the initial delay before emitting a single 0L
2537 * @param unit
2538 * time units to use for {@code delay}
2539 * @param scheduler
2540 * the {@link Scheduler} to use for scheduling the item
2541 * @return an Observable that emits one item after a specified delay, on a specified Scheduler, and then
2542 * completes
2543 * @see <a href="http://reactivex.io/documentation/operators/timer.html">ReactiveX operators documentation: Timer</a>
2544 */
2545 public final static Observable<Long> timer(long delay, TimeUnit unit, Scheduler scheduler) {
2546 return create(new OnSubscribeTimerOnce(delay, unit, scheduler));
2547 }
2548
2549 /**
2550 * Constructs an Observable that creates a dependent resource object which is disposed of on unsubscription.
2551 * <p>
2552 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/using.png" alt="">
2553 * <dl>
2554 * <dt><b>Scheduler:</b></dt>
2555 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
2556 * </dl>
2557 *
2558 * @param resourceFactory
2559 * the factory function to create a resource object that depends on the Observable
2560 * @param observableFactory
2561 * the factory function to create an Observable
2562 * @param disposeAction
2563 * the function that will dispose of the resource
2564 * @return the Observable whose lifetime controls the lifetime of the dependent resource object
2565 * @see <a href="http://reactivex.io/documentation/operators/using.html">ReactiveX operators documentation: Using</a>
2566 */
2567 public final static <T, Resource> Observable<T> using(
2568 final Func0<Resource> resourceFactory,
2569 final Func1<? super Resource, ? extends Observable<? extends T>> observableFactory,
2570 final Action1<? super Resource> disposeAction) {
2571 return using(resourceFactory, observableFactory, disposeAction, false);
2572 }
2573
2574 /**
2575 * Constructs an Observable that creates a dependent resource object which is disposed of just before
2576 * termination if you have set {@code disposeEagerly} to {@code true} and unsubscription does not occur
2577 * before termination. Otherwise resource disposal will occur on unsubscription. Eager disposal is
2578 * particularly appropriate for a synchronous Observable that resuses resources. {@code disposeAction} will
2579 * only be called once per subscription.
2580 * <p>
2581 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/using.png" alt="">
2582 * <dl>
2583 * <dt><b>Scheduler:</b></dt>
2584 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
2585 * </dl>
2586 *
2587 * @warn "Backpressure Support" section missing from javadoc
2588 * @param resourceFactory
2589 * the factory function to create a resource object that depends on the Observable
2590 * @param observableFactory
2591 * the factory function to create an Observable
2592 * @param disposeAction
2593 * the function that will dispose of the resource
2594 * @param disposeEagerly
2595 * if {@code true} then disposal will happen either on unsubscription or just before emission of
2596 * a terminal event ({@code onComplete} or {@code onError}).
2597 * @return the Observable whose lifetime controls the lifetime of the dependent resource object
2598 * @see <a href="http://reactivex.io/documentation/operators/using.html">ReactiveX operators documentation: Using</a>
2599 * @Experimental The behavior of this can change at any time.
2600 * @since (if this graduates from Experimental/Beta to supported, replace
2601 * this parenthetical with the release number)
2602 */
2603 @Experimental
2604 public final static <T, Resource> Observable<T> using(
2605 final Func0<Resource> resourceFactory,
2606 final Func1<? super Resource, ? extends Observable<? extends T>> observableFactory,
2607 final Action1<? super Resource> disposeAction, boolean disposeEagerly) {
2608 return create(new OnSubscribeUsing<T, Resource>(resourceFactory, observableFactory, disposeAction, disposeEagerly));
2609 }
2610
2611 /**
2612 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2613 * items emitted, in sequence, by an Iterable of other Observables.
2614 * <p>
2615 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2616 * will be the result of the function applied to the first item emitted by each of the source Observables;
2617 * the second item emitted by the new Observable will be the result of the function applied to the second
2618 * item emitted by each of those Observables; and so forth.
2619 * <p>
2620 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@code onNext} as many times as
2621 * the number of {@code onNext} invokations of the source Observable that emits the fewest items.
2622 * <p>
2623 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
2624 * <dl>
2625 * <dt><b>Scheduler:</b></dt>
2626 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2627 * </dl>
2628 *
2629 * @param ws
2630 * an Iterable of source Observables
2631 * @param zipFunction
2632 * a function that, when applied to an item emitted by each of the source Observables, results in
2633 * an item that will be emitted by the resulting Observable
2634 * @return an Observable that emits the zipped results
2635 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2636 */
2637 public final static <R> Observable<R> zip(Iterable<? extends Observable<?>> ws, FuncN<? extends R> zipFunction) {
2638 List<Observable<?>> os = new ArrayList<Observable<?>>();
2639 for (Observable<?> o : ws) {
2640 os.add(o);
2641 }
2642 return Observable.just(os.toArray(new Observable<?>[os.size()])).lift(new OperatorZip<R>(zipFunction));
2643 }
2644
2645 /**
2646 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2647 * <i>n</i> items emitted, in sequence, by the <i>n</i> Observables emitted by a specified Observable.
2648 * <p>
2649 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2650 * will be the result of the function applied to the first item emitted by each of the Observables emitted
2651 * by the source Observable; the second item emitted by the new Observable will be the result of the
2652 * function applied to the second item emitted by each of those Observables; and so forth.
2653 * <p>
2654 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@code onNext} as many times as
2655 * the number of {@code onNext} invokations of the source Observable that emits the fewest items.
2656 * <p>
2657 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.o.png" alt="">
2658 * <dl>
2659 * <dt><b>Scheduler:</b></dt>
2660 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2661 * </dl>
2662 *
2663 * @param ws
2664 * an Observable of source Observables
2665 * @param zipFunction
2666 * a function that, when applied to an item emitted by each of the Observables emitted by
2667 * {@code ws}, results in an item that will be emitted by the resulting Observable
2668 * @return an Observable that emits the zipped results
2669 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2670 */
2671 public final static <R> Observable<R> zip(Observable<? extends Observable<?>> ws, final FuncN<? extends R> zipFunction) {
2672 return ws.toList().map(new Func1<List<? extends Observable<?>>, Observable<?>[]>() {
2673
2674 @Override
2675 public Observable<?>[] call(List<? extends Observable<?>> o) {
2676 return o.toArray(new Observable<?>[o.size()]);
2677 }
2678
2679 }).lift(new OperatorZip<R>(zipFunction));
2680 }
2681
2682 /**
2683 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2684 * two items emitted, in sequence, by two other Observables.
2685 * <p>
2686 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
2687 * <p>
2688 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2689 * will be the result of the function applied to the first item emitted by {@code o1} and the first item
2690 * emitted by {@code o2}; the second item emitted by the new Observable will be the result of the function
2691 * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth.
2692 * <p>
2693 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
2694 * as many times as the number of {@code onNext} invocations of the source Observable that emits the fewest
2695 * items.
2696 * <dl>
2697 * <dt><b>Scheduler:</b></dt>
2698 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2699 * </dl>
2700 *
2701 * @param o1
2702 * the first source Observable
2703 * @param o2
2704 * a second source Observable
2705 * @param zipFunction
2706 * a function that, when applied to an item emitted by each of the source Observables, results
2707 * in an item that will be emitted by the resulting Observable
2708 * @return an Observable that emits the zipped results
2709 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2710 */
2711 public final static <T1, T2, R> Observable<R> zip(Observable<? extends T1> o1, Observable<? extends T2> o2, final Func2<? super T1, ? super T2, ? extends R> zipFunction) {
2712 return just(new Observable<?>[] { o1, o2 }).lift(new OperatorZip<R>(zipFunction));
2713 }
2714
2715 /**
2716 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2717 * three items emitted, in sequence, by three other Observables.
2718 * <p>
2719 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
2720 * <p>
2721 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2722 * will be the result of the function applied to the first item emitted by {@code o1}, the first item
2723 * emitted by {@code o2}, and the first item emitted by {@code o3}; the second item emitted by the new
2724 * Observable will be the result of the function applied to the second item emitted by {@code o1}, the
2725 * second item emitted by {@code o2}, and the second item emitted by {@code o3}; and so forth.
2726 * <p>
2727 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
2728 * as many times as the number of {@code onNext} invocations of the source Observable that emits the fewest
2729 * items.
2730 * <dl>
2731 * <dt><b>Scheduler:</b></dt>
2732 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2733 * </dl>
2734 *
2735 * @param o1
2736 * the first source Observable
2737 * @param o2
2738 * a second source Observable
2739 * @param o3
2740 * a third source Observable
2741 * @param zipFunction
2742 * a function that, when applied to an item emitted by each of the source Observables, results in
2743 * an item that will be emitted by the resulting Observable
2744 * @return an Observable that emits the zipped results
2745 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2746 */
2747 public final static <T1, T2, T3, R> Observable<R> zip(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Func3<? super T1, ? super T2, ? super T3, ? extends R> zipFunction) {
2748 return just(new Observable<?>[] { o1, o2, o3 }).lift(new OperatorZip<R>(zipFunction));
2749 }
2750
2751 /**
2752 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2753 * four items emitted, in sequence, by four other Observables.
2754 * <p>
2755 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
2756 * <p>
2757 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2758 * will be the result of the function applied to the first item emitted by {@code o1}, the first item
2759 * emitted by {@code o2}, the first item emitted by {@code o3}, and the first item emitted by {@code 04};
2760 * the second item emitted by the new Observable will be the result of the function applied to the second
2761 * item emitted by each of those Observables; and so forth.
2762 * <p>
2763 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
2764 * as many times as the number of {@code onNext} invocations of the source Observable that emits the fewest
2765 * items.
2766 * <dl>
2767 * <dt><b>Scheduler:</b></dt>
2768 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2769 * </dl>
2770 *
2771 * @param o1
2772 * the first source Observable
2773 * @param o2
2774 * a second source Observable
2775 * @param o3
2776 * a third source Observable
2777 * @param o4
2778 * a fourth source Observable
2779 * @param zipFunction
2780 * a function that, when applied to an item emitted by each of the source Observables, results in
2781 * an item that will be emitted by the resulting Observable
2782 * @return an Observable that emits the zipped results
2783 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2784 */
2785 public final static <T1, T2, T3, T4, R> Observable<R> zip(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Func4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> zipFunction) {
2786 return just(new Observable<?>[] { o1, o2, o3, o4 }).lift(new OperatorZip<R>(zipFunction));
2787 }
2788
2789 /**
2790 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2791 * five items emitted, in sequence, by five other Observables.
2792 * <p>
2793 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
2794 * <p>
2795 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2796 * will be the result of the function applied to the first item emitted by {@code o1}, the first item
2797 * emitted by {@code o2}, the first item emitted by {@code o3}, the first item emitted by {@code o4}, and
2798 * the first item emitted by {@code o5}; the second item emitted by the new Observable will be the result of
2799 * the function applied to the second item emitted by each of those Observables; and so forth.
2800 * <p>
2801 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
2802 * as many times as the number of {@code onNext} invocations of the source Observable that emits the fewest
2803 * items.
2804 * <dl>
2805 * <dt><b>Scheduler:</b></dt>
2806 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2807 * </dl>
2808 *
2809 * @param o1
2810 * the first source Observable
2811 * @param o2
2812 * a second source Observable
2813 * @param o3
2814 * a third source Observable
2815 * @param o4
2816 * a fourth source Observable
2817 * @param o5
2818 * a fifth source Observable
2819 * @param zipFunction
2820 * a function that, when applied to an item emitted by each of the source Observables, results in
2821 * an item that will be emitted by the resulting Observable
2822 * @return an Observable that emits the zipped results
2823 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2824 */
2825 public final static <T1, T2, T3, T4, T5, R> Observable<R> zip(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5, Func5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> zipFunction) {
2826 return just(new Observable<?>[] { o1, o2, o3, o4, o5 }).lift(new OperatorZip<R>(zipFunction));
2827 }
2828
2829 /**
2830 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2831 * six items emitted, in sequence, by six other Observables.
2832 * <p>
2833 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
2834 * <p>
2835 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2836 * will be the result of the function applied to the first item emitted by each source Observable, the
2837 * second item emitted by the new Observable will be the result of the function applied to the second item
2838 * emitted by each of those Observables, and so forth.
2839 * <p>
2840 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
2841 * as many times as the number of {@code onNext} invocations of the source Observable that emits the fewest
2842 * items.
2843 * <dl>
2844 * <dt><b>Scheduler:</b></dt>
2845 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2846 * </dl>
2847 *
2848 * @param o1
2849 * the first source Observable
2850 * @param o2
2851 * a second source Observable
2852 * @param o3
2853 * a third source Observable
2854 * @param o4
2855 * a fourth source Observable
2856 * @param o5
2857 * a fifth source Observable
2858 * @param o6
2859 * a sixth source Observable
2860 * @param zipFunction
2861 * a function that, when applied to an item emitted by each of the source Observables, results in
2862 * an item that will be emitted by the resulting Observable
2863 * @return an Observable that emits the zipped results
2864 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2865 */
2866 public final static <T1, T2, T3, T4, T5, T6, R> Observable<R> zip(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5, Observable<? extends T6> o6,
2867 Func6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> zipFunction) {
2868 return just(new Observable<?>[] { o1, o2, o3, o4, o5, o6 }).lift(new OperatorZip<R>(zipFunction));
2869 }
2870
2871 /**
2872 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2873 * seven items emitted, in sequence, by seven other Observables.
2874 * <p>
2875 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
2876 * <p>
2877 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2878 * will be the result of the function applied to the first item emitted by each source Observable, the
2879 * second item emitted by the new Observable will be the result of the function applied to the second item
2880 * emitted by each of those Observables, and so forth.
2881 * <p>
2882 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
2883 * as many times as the number of {@code onNext} invocations of the source Observable that emits the fewest
2884 * items.
2885 * <dl>
2886 * <dt><b>Scheduler:</b></dt>
2887 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2888 * </dl>
2889 *
2890 * @param o1
2891 * the first source Observable
2892 * @param o2
2893 * a second source Observable
2894 * @param o3
2895 * a third source Observable
2896 * @param o4
2897 * a fourth source Observable
2898 * @param o5
2899 * a fifth source Observable
2900 * @param o6
2901 * a sixth source Observable
2902 * @param o7
2903 * a seventh source Observable
2904 * @param zipFunction
2905 * a function that, when applied to an item emitted by each of the source Observables, results in
2906 * an item that will be emitted by the resulting Observable
2907 * @return an Observable that emits the zipped results
2908 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2909 */
2910 public final static <T1, T2, T3, T4, T5, T6, T7, R> Observable<R> zip(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5, Observable<? extends T6> o6, Observable<? extends T7> o7,
2911 Func7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> zipFunction) {
2912 return just(new Observable<?>[] { o1, o2, o3, o4, o5, o6, o7 }).lift(new OperatorZip<R>(zipFunction));
2913 }
2914
2915 /**
2916 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2917 * eight items emitted, in sequence, by eight other Observables.
2918 * <p>
2919 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
2920 * <p>
2921 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2922 * will be the result of the function applied to the first item emitted by each source Observable, the
2923 * second item emitted by the new Observable will be the result of the function applied to the second item
2924 * emitted by each of those Observables, and so forth.
2925 * <p>
2926 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
2927 * as many times as the number of {@code onNext} invocations of the source Observable that emits the fewest
2928 * items.
2929 * <dl>
2930 * <dt><b>Scheduler:</b></dt>
2931 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2932 * </dl>
2933 *
2934 * @param o1
2935 * the first source Observable
2936 * @param o2
2937 * a second source Observable
2938 * @param o3
2939 * a third source Observable
2940 * @param o4
2941 * a fourth source Observable
2942 * @param o5
2943 * a fifth source Observable
2944 * @param o6
2945 * a sixth source Observable
2946 * @param o7
2947 * a seventh source Observable
2948 * @param o8
2949 * an eighth source Observable
2950 * @param zipFunction
2951 * a function that, when applied to an item emitted by each of the source Observables, results in
2952 * an item that will be emitted by the resulting Observable
2953 * @return an Observable that emits the zipped results
2954 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2955 */
2956 public final static <T1, T2, T3, T4, T5, T6, T7, T8, R> Observable<R> zip(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5, Observable<? extends T6> o6, Observable<? extends T7> o7, Observable<? extends T8> o8,
2957 Func8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> zipFunction) {
2958 return just(new Observable<?>[] { o1, o2, o3, o4, o5, o6, o7, o8 }).lift(new OperatorZip<R>(zipFunction));
2959 }
2960
2961 /**
2962 * Returns an Observable that emits the results of a specified combiner function applied to combinations of
2963 * nine items emitted, in sequence, by nine other Observables.
2964 * <p>
2965 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
2966 * <p>
2967 * {@code zip} applies this function in strict sequence, so the first item emitted by the new Observable
2968 * will be the result of the function applied to the first item emitted by each source Observable, the
2969 * second item emitted by the new Observable will be the result of the function applied to the second item
2970 * emitted by each of those Observables, and so forth.
2971 * <p>
2972 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
2973 * as many times as the number of {@code onNext} invocations of the source Observable that emits the fewest
2974 * items.
2975 * <dl>
2976 * <dt><b>Scheduler:</b></dt>
2977 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2978 * </dl>
2979 *
2980 * @param o1
2981 * the first source Observable
2982 * @param o2
2983 * a second source Observable
2984 * @param o3
2985 * a third source Observable
2986 * @param o4
2987 * a fourth source Observable
2988 * @param o5
2989 * a fifth source Observable
2990 * @param o6
2991 * a sixth source Observable
2992 * @param o7
2993 * a seventh source Observable
2994 * @param o8
2995 * an eighth source Observable
2996 * @param o9
2997 * a ninth source Observable
2998 * @param zipFunction
2999 * a function that, when applied to an item emitted by each of the source Observables, results in
3000 * an item that will be emitted by the resulting Observable
3001 * @return an Observable that emits the zipped results
3002 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
3003 */
3004 public final static <T1, T2, T3, T4, T5, T6, T7, T8, T9, R> Observable<R> zip(Observable<? extends T1> o1, Observable<? extends T2> o2, Observable<? extends T3> o3, Observable<? extends T4> o4, Observable<? extends T5> o5, Observable<? extends T6> o6, Observable<? extends T7> o7, Observable<? extends T8> o8,
3005 Observable<? extends T9> o9, Func9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> zipFunction) {
3006 return just(new Observable<?>[] { o1, o2, o3, o4, o5, o6, o7, o8, o9 }).lift(new OperatorZip<R>(zipFunction));
3007 }
3008
3009 /**
3010 * Returns an Observable that emits a Boolean that indicates whether all of the items emitted by the source
3011 * Observable satisfy a condition.
3012 * <p>
3013 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/all.png" alt="">
3014 * <dl>
3015 * <dt><b>Scheduler:</b></dt>
3016 * <dd>{@code all} does not operate by default on a particular {@link Scheduler}.</dd>
3017 * </dl>
3018 *
3019 * @param predicate
3020 * a function that evaluates an item and returns a Boolean
3021 * @return an Observable that emits {@code true} if all items emitted by the source Observable satisfy the
3022 * predicate; otherwise, {@code false}
3023 * @see <a href="http://reactivex.io/documentation/operators/all.html">ReactiveX operators documentation: All</a>
3024 */
3025 public final Observable<Boolean> all(Func1<? super T, Boolean> predicate) {
3026 return lift(new OperatorAll<T>(predicate));
3027 }
3028
3029 /**
3030 * Mirrors the Observable (current or provided) that first either emits an item or sends a termination
3031 * notification.
3032 * <p>
3033 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
3034 * <dl>
3035 * <dt><b>Scheduler:</b></dt>
3036 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
3037 * </dl>
3038 *
3039 * @param t1
3040 * an Observable competing to react first
3041 * @return an Observable that emits the same sequence as whichever of the source Observables first
3042 * emitted an item or sent a termination notification
3043 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
3044 */
3045 public final Observable<T> ambWith(Observable<? extends T> t1) {
3046 return amb(this, t1);
3047 }
3048
3049 /**
3050 * Portrays a object of an Observable subclass as a simple Observable object. This is useful, for instance,
3051 * when you have an implementation of a subclass of Observable but you want to hide the properties and
3052 * methods of this subclass from whomever you are passing the Observable to.
3053 * <dl>
3054 * <dt><b>Scheduler:</b></dt>
3055 * <dd>{@code asObservable} does not operate by default on a particular {@link Scheduler}.</dd>
3056 * </dl>
3057 *
3058 * @return an Observable that hides the identity of this Observable
3059 */
3060 public final Observable<T> asObservable() {
3061 return lift(OperatorAsObservable.<T>instance());
3062 }
3063
3064 /**
3065 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3066 * Observable emits connected, non-overlapping buffers. It emits the current buffer and replaces it with a
3067 * new buffer whenever the Observable produced by the specified {@code bufferClosingSelector} emits an item.
3068 * <p>
3069 * <img width="640" height="395" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer1.png" alt="">
3070 * <dl>
3071 * <dt><b>Backpressure Support:</b></dt>
3072 * <dd>This operator does not support backpressure as it is instead controlled by the given Observables and
3073 * buffers data. It requests {@code Long.MAX_VALUE} upstream and does not obey downstream requests.</dd>
3074 * <dt><b>Scheduler:</b></dt>
3075 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
3076 * </dl>
3077 *
3078 * @param bufferClosingSelector
3079 * a {@link Func0} that produces an Observable that governs the boundary between buffers.
3080 * Whenever this {@code Observable} emits an item, {@code buffer} emits the current buffer and
3081 * begins to fill a new one
3082 * @return an Observable that emits a connected, non-overlapping buffer of items from the source Observable
3083 * each time the Observable created with the {@code bufferClosingSelector} argument emits an item
3084 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3085 */
3086 public final <TClosing> Observable<List<T>> buffer(Func0<? extends Observable<? extends TClosing>> bufferClosingSelector) {
3087 return lift(new OperatorBufferWithSingleObservable<T, TClosing>(bufferClosingSelector, 16));
3088 }
3089
3090 /**
3091 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3092 * Observable emits connected, non-overlapping buffers, each containing {@code count} items. When the source
3093 * Observable completes or encounters an error, the resulting Observable emits the current buffer and
3094 * propagates the notification from the source Observable.
3095 * <p>
3096 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer3.png" alt="">
3097 * <dl>
3098 * <dt><b>Scheduler:</b></dt>
3099 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
3100 * </dl>
3101 *
3102 * @param count
3103 * the maximum number of items in each buffer before it should be emitted
3104 * @return an Observable that emits connected, non-overlapping buffers, each containing at most
3105 * {@code count} items from the source Observable
3106 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3107 */
3108 public final Observable<List<T>> buffer(int count) {
3109 return buffer(count, count);
3110 }
3111
3112 /**
3113 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3114 * Observable emits buffers every {@code skip} items, each containing {@code count} items. When the source
3115 * Observable completes or encounters an error, the resulting Observable emits the current buffer and
3116 * propagates the notification from the source Observable.
3117 * <p>
3118 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer4.png" alt="">
3119 * <dl>
3120 * <dt><b>Scheduler:</b></dt>
3121 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
3122 * </dl>
3123 *
3124 * @param count
3125 * the maximum size of each buffer before it should be emitted
3126 * @param skip
3127 * how many items emitted by the source Observable should be skipped before starting a new
3128 * buffer. Note that when {@code skip} and {@code count} are equal, this is the same operation as
3129 * {@link #buffer(int)}.
3130 * @return an Observable that emits buffers for every {@code skip} item from the source Observable and
3131 * containing at most {@code count} items
3132 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3133 */
3134 public final Observable<List<T>> buffer(int count, int skip) {
3135 return lift(new OperatorBufferWithSize<T>(count, skip));
3136 }
3137
3138 /**
3139 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3140 * Observable starts a new buffer periodically, as determined by the {@code timeshift} argument. It emits
3141 * each buffer after a fixed timespan, specified by the {@code timespan} argument. When the source
3142 * Observable completes or encounters an error, the resulting Observable emits the current buffer and
3143 * propagates the notification from the source Observable.
3144 * <p>
3145 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer7.png" alt="">
3146 * <dl>
3147 * <dt><b>Backpressure Support:</b></dt>
3148 * <dd>This operator does not support backpressure as it uses time. It requests {@code Long.MAX_VALUE}
3149 * upstream and does not obey downstream requests.</dd>
3150 * <dt><b>Scheduler:</b></dt>
3151 * <dd>This version of {@code buffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
3152 * </dl>
3153 *
3154 * @param timespan
3155 * the period of time each buffer collects items before it is emitted
3156 * @param timeshift
3157 * the period of time after which a new buffer will be created
3158 * @param unit
3159 * the unit of time that applies to the {@code timespan} and {@code timeshift} arguments
3160 * @return an Observable that emits new buffers of items emitted by the source Observable periodically after
3161 * a fixed timespan has elapsed
3162 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3163 */
3164 public final Observable<List<T>> buffer(long timespan, long timeshift, TimeUnit unit) {
3165 return buffer(timespan, timeshift, unit, Schedulers.computation());
3166 }
3167
3168 /**
3169 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3170 * Observable starts a new buffer periodically, as determined by the {@code timeshift} argument, and on the
3171 * specified {@code scheduler}. It emits each buffer after a fixed timespan, specified by the
3172 * {@code timespan} argument. When the source Observable completes or encounters an error, the resulting
3173 * Observable emits the current buffer and propagates the notification from the source Observable.
3174 * <p>
3175 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer7.s.png" alt="">
3176 * <dl>
3177 * <dt><b>Backpressure Support:</b></dt>
3178 * <dd>This operator does not support backpressure as it uses time. It requests {@code Long.MAX_VALUE}
3179 * upstream and does not obey downstream requests.</dd>
3180 * <dt><b>Scheduler:</b></dt>
3181 * <dd>you specify which {@link Scheduler} this operator will use</dd>
3182 * </dl>
3183 *
3184 * @param timespan
3185 * the period of time each buffer collects items before it is emitted
3186 * @param timeshift
3187 * the period of time after which a new buffer will be created
3188 * @param unit
3189 * the unit of time that applies to the {@code timespan} and {@code timeshift} arguments
3190 * @param scheduler
3191 * the {@link Scheduler} to use when determining the end and start of a buffer
3192 * @return an Observable that emits new buffers of items emitted by the source Observable periodically after
3193 * a fixed timespan has elapsed
3194 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3195 */
3196 public final Observable<List<T>> buffer(long timespan, long timeshift, TimeUnit unit, Scheduler scheduler) {
3197 return lift(new OperatorBufferWithTime<T>(timespan, timeshift, unit, Integer.MAX_VALUE, scheduler));
3198 }
3199
3200 /**
3201 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3202 * Observable emits connected, non-overlapping buffers, each of a fixed duration specified by the
3203 * {@code timespan} argument. When the source Observable completes or encounters an error, the resulting
3204 * Observable emits the current buffer and propagates the notification from the source Observable.
3205 * <p>
3206 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer5.png" alt="">
3207 * <dl>
3208 * <dt><b>Backpressure Support:</b></dt>
3209 * <dd>This operator does not support backpressure as it uses time. It requests {@code Long.MAX_VALUE}
3210 * upstream and does not obey downstream requests.</dd>
3211 * <dt><b>Scheduler:</b></dt>
3212 * <dd>This version of {@code buffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
3213 * </dl>
3214 *
3215 * @param timespan
3216 * the period of time each buffer collects items before it is emitted and replaced with a new
3217 * buffer
3218 * @param unit
3219 * the unit of time that applies to the {@code timespan} argument
3220 * @return an Observable that emits connected, non-overlapping buffers of items emitted by the source
3221 * Observable within a fixed duration
3222 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3223 */
3224 public final Observable<List<T>> buffer(long timespan, TimeUnit unit) {
3225 return buffer(timespan, unit, Integer.MAX_VALUE, Schedulers.computation());
3226 }
3227
3228 /**
3229 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3230 * Observable emits connected, non-overlapping buffers, each of a fixed duration specified by the
3231 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
3232 * first). When the source Observable completes or encounters an error, the resulting Observable emits the
3233 * current buffer and propagates the notification from the source Observable.
3234 * <p>
3235 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer6.png" alt="">
3236 * <dl>
3237 * <dt><b>Backpressure Support:</b></dt>
3238 * <dd>This operator does not support backpressure as it uses time. It requests {@code Long.MAX_VALUE}
3239 * upstream and does not obey downstream requests.</dd>
3240 * <dt><b>Scheduler:</b></dt>
3241 * <dd>This version of {@code buffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
3242 * </dl>
3243 *
3244 * @param timespan
3245 * the period of time each buffer collects items before it is emitted and replaced with a new
3246 * buffer
3247 * @param unit
3248 * the unit of time which applies to the {@code timespan} argument
3249 * @param count
3250 * the maximum size of each buffer before it is emitted
3251 * @return an Observable that emits connected, non-overlapping buffers of items emitted by the source
3252 * Observable, after a fixed duration or when the buffer reaches maximum capacity (whichever occurs
3253 * first)
3254 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3255 */
3256 public final Observable<List<T>> buffer(long timespan, TimeUnit unit, int count) {
3257 return lift(new OperatorBufferWithTime<T>(timespan, timespan, unit, count, Schedulers.computation()));
3258 }
3259
3260 /**
3261 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3262 * Observable emits connected, non-overlapping buffers, each of a fixed duration specified by the
3263 * {@code timespan} argument as measured on the specified {@code scheduler}, or a maximum size specified by
3264 * the {@code count} argument (whichever is reached first). When the source Observable completes or
3265 * encounters an error, the resulting Observable emits the current buffer and propagates the notification
3266 * from the source Observable.
3267 * <p>
3268 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer6.s.png" alt="">
3269 * <dl>
3270 * <dt><b>Backpressure Support:</b></dt>
3271 * <dd>This operator does not support backpressure as it uses time. It requests {@code Long.MAX_VALUE}
3272 * upstream and does not obey downstream requests.</dd>
3273 * <dt><b>Scheduler:</b></dt>
3274 * <dd>you specify which {@link Scheduler} this operator will use</dd>
3275 * </dl>
3276 *
3277 * @param timespan
3278 * the period of time each buffer collects items before it is emitted and replaced with a new
3279 * buffer
3280 * @param unit
3281 * the unit of time which applies to the {@code timespan} argument
3282 * @param count
3283 * the maximum size of each buffer before it is emitted
3284 * @param scheduler
3285 * the {@link Scheduler} to use when determining the end and start of a buffer
3286 * @return an Observable that emits connected, non-overlapping buffers of items emitted by the source
3287 * Observable after a fixed duration or when the buffer reaches maximum capacity (whichever occurs
3288 * first)
3289 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3290 */
3291 public final Observable<List<T>> buffer(long timespan, TimeUnit unit, int count, Scheduler scheduler) {
3292 return lift(new OperatorBufferWithTime<T>(timespan, timespan, unit, count, scheduler));
3293 }
3294
3295 /**
3296 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3297 * Observable emits connected, non-overlapping buffers, each of a fixed duration specified by the
3298 * {@code timespan} argument and on the specified {@code scheduler}. When the source Observable completes or
3299 * encounters an error, the resulting Observable emits the current buffer and propagates the notification
3300 * from the source Observable.
3301 * <p>
3302 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer5.s.png" alt="">
3303 * <dl>
3304 * <dt><b>Backpressure Support:</b></dt>
3305 * <dd>This operator does not support backpressure as it uses time. It requests {@code Long.MAX_VALUE}
3306 * upstream and does not obey downstream requests.</dd>
3307 * <dt><b>Scheduler:</b></dt>
3308 * <dd>you specify which {@link Scheduler} this operator will use</dd>
3309 * </dl>
3310 *
3311 * @param timespan
3312 * the period of time each buffer collects items before it is emitted and replaced with a new
3313 * buffer
3314 * @param unit
3315 * the unit of time which applies to the {@code timespan} argument
3316 * @param scheduler
3317 * the {@link Scheduler} to use when determining the end and start of a buffer
3318 * @return an Observable that emits connected, non-overlapping buffers of items emitted by the source
3319 * Observable within a fixed duration
3320 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3321 */
3322 public final Observable<List<T>> buffer(long timespan, TimeUnit unit, Scheduler scheduler) {
3323 return buffer(timespan, timespan, unit, scheduler);
3324 }
3325
3326 /**
3327 * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
3328 * Observable emits buffers that it creates when the specified {@code bufferOpenings} Observable emits an
3329 * item, and closes when the Observable returned from {@code bufferClosingSelector} emits an item.
3330 * <p>
3331 * <img width="640" height="470" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer2.png" alt="">
3332 * <dl>
3333 * <dt><b>Backpressure Support:</b></dt>
3334 * <dd>This operator does not support backpressure as it is instead controlled by the given Observables and
3335 * buffers data. It requests {@code Long.MAX_VALUE} upstream and does not obey downstream requests.</dd>
3336 * <dt><b>Scheduler:</b></dt>
3337 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
3338 * </dl>
3339 *
3340 * @param bufferOpenings
3341 * the Observable that, when it emits an item, causes a new buffer to be created
3342 * @param bufferClosingSelector
3343 * the {@link Func1} that is used to produce an Observable for every buffer created. When this
3344 * Observable emits an item, the associated buffer is emitted.
3345 * @return an Observable that emits buffers, containing items from the source Observable, that are created
3346 * and closed when the specified Observables emit items
3347 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3348 */
3349 public final <TOpening, TClosing> Observable<List<T>> buffer(Observable<? extends TOpening> bufferOpenings, Func1<? super TOpening, ? extends Observable<? extends TClosing>> bufferClosingSelector) {
3350 return lift(new OperatorBufferWithStartEndObservable<T, TOpening, TClosing>(bufferOpenings, bufferClosingSelector));
3351 }
3352
3353 /**
3354 * Returns an Observable that emits non-overlapping buffered items from the source Observable each time the
3355 * specified boundary Observable emits an item.
3356 * <p>
3357 * <img width="640" height="395" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer8.png" alt="">
3358 * <p>
3359 * Completion of either the source or the boundary Observable causes the returned Observable to emit the
3360 * latest buffer and complete.
3361 * <dl>
3362 * <dt><b>Backpressure Support:</b></dt>
3363 * <dd>This operator does not support backpressure as it is instead controlled by the {@code Observable}
3364 * {@code boundary} and buffers data. It requests {@code Long.MAX_VALUE} upstream and does not obey
3365 * downstream requests.</dd>
3366 * <dt><b>Scheduler:</b></dt>
3367 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
3368 * </dl>
3369 *
3370 * @param <B>
3371 * the boundary value type (ignored)
3372 * @param boundary
3373 * the boundary Observable
3374 * @return an Observable that emits buffered items from the source Observable when the boundary Observable
3375 * emits an item
3376 * @see #buffer(rx.Observable, int)
3377 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3378 */
3379 public final <B> Observable<List<T>> buffer(Observable<B> boundary) {
3380 return buffer(boundary, 16);
3381 }
3382
3383 /**
3384 * Returns an Observable that emits non-overlapping buffered items from the source Observable each time the
3385 * specified boundary Observable emits an item.
3386 * <p>
3387 * <img width="640" height="395" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer8.png" alt="">
3388 * <p>
3389 * Completion of either the source or the boundary Observable causes the returned Observable to emit the
3390 * latest buffer and complete.
3391 * <dl>
3392 * <dt><b>Backpressure Support:</b></dt>
3393 * <dd>This operator does not support backpressure as it is instead controlled by the {@code Observable}
3394 * {@code boundary} and buffers data. It requests {@code Long.MAX_VALUE} upstream and does not obey
3395 * downstream requests.</dd>
3396 * <dt><b>Scheduler:</b></dt>
3397 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
3398 * </dl>
3399 *
3400 * @param <B>
3401 * the boundary value type (ignored)
3402 * @param boundary
3403 * the boundary Observable
3404 * @param initialCapacity
3405 * the initial capacity of each buffer chunk
3406 * @return an Observable that emits buffered items from the source Observable when the boundary Observable
3407 * emits an item
3408 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
3409 * @see #buffer(rx.Observable, int)
3410 */
3411 public final <B> Observable<List<T>> buffer(Observable<B> boundary, int initialCapacity) {
3412 return lift(new OperatorBufferWithSingleObservable<T, B>(boundary, initialCapacity));
3413 }
3414
3415 /**
3416 * Caches the emissions from the source Observable and replays them in order to any subsequent Subscribers.
3417 * This method has similar behavior to {@link #replay} except that this auto-subscribes to the source
3418 * Observable rather than returning a {@link ConnectableObservable} for which you must call
3419 * {@code connect} to activate the subscription.
3420 * <p>
3421 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/cache.png" alt="">
3422 * <p>
3423 * This is useful when you want an Observable to cache responses and you can't control the
3424 * subscribe/unsubscribe behavior of all the {@link Subscriber}s.
3425 * <p>
3426 * When you call {@code cache}, it does not yet subscribe to the source Observable and so does not yet
3427 * begin cacheing items. This only happens when the first Subscriber calls the resulting Observable's
3428 * {@code subscribe} method.
3429 * <p>
3430 * <em>Note:</em> You sacrifice the ability to unsubscribe from the origin when you use the {@code cache}
3431 * Observer so be careful not to use this Observer on Observables that emit an infinite or very large number
3432 * of items that will use up memory.
3433 * <dl>
3434 * <dt><b>Backpressure Support:</b></dt>
3435 * <dd>This operator does not support upstream backpressure as it is purposefully requesting and caching
3436 * everything emitted.</dd>
3437 * <dt><b>Scheduler:</b></dt>
3438 * <dd>{@code cache} does not operate by default on a particular {@link Scheduler}.</dd>
3439 * </dl>
3440 *
3441 * @return an Observable that, when first subscribed to, caches all of its items and notifications for the
3442 * benefit of subsequent subscribers
3443 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
3444 */
3445 public final Observable<T> cache() {
3446 return create(new OnSubscribeCache<T>(this));
3447 }
3448
3449 /**
3450 * Caches emissions from the source Observable and replays them in order to any subsequent Subscribers.
3451 * This method has similar behavior to {@link #replay} except that this auto-subscribes to the source
3452 * Observable rather than returning a {@link ConnectableObservable} for which you must call
3453 * {@code connect} to activate the subscription.
3454 * <p>
3455 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/cache.png" alt="">
3456 * <p>
3457 * This is useful when you want an Observable to cache responses and you can't control the
3458 * subscribe/unsubscribe behavior of all the {@link Subscriber}s.
3459 * <p>
3460 * When you call {@code cache}, it does not yet subscribe to the source Observable and so does not yet
3461 * begin cacheing items. This only happens when the first Subscriber calls the resulting Observable's
3462 * {@code subscribe} method.
3463 * <p>
3464 * <em>Note:</em> You sacrifice the ability to unsubscribe from the origin when you use the {@code cache}
3465 * Observer so be careful not to use this Observer on Observables that emit an infinite or very large number
3466 * of items that will use up memory.
3467 * <dl>
3468 * <dt><b>Backpressure Support:</b></dt>
3469 * <dd>This operator does not support upstream backpressure as it is purposefully requesting and caching
3470 * everything emitted.</dd>
3471 * <dt><b>Scheduler:</b></dt>
3472 * <dd>{@code cache} does not operate by default on a particular {@link Scheduler}.</dd>
3473 * </dl>
3474 *
3475 * @param capacity hint for number of items to cache (for optimizing underlying data structure)
3476 * @return an Observable that, when first subscribed to, caches all of its items and notifications for the
3477 * benefit of subsequent subscribers
3478 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
3479 */
3480 public final Observable<T> cache(int capacity) {
3481 return create(new OnSubscribeCache<T>(this, capacity));
3482 }
3483
3484 /**
3485 * Returns an Observable that emits the items emitted by the source Observable, converted to the specified
3486 * type.
3487 * <p>
3488 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/cast.png" alt="">
3489 * <dl>
3490 * <dt><b>Scheduler:</b></dt>
3491 * <dd>{@code cast} does not operate by default on a particular {@link Scheduler}.</dd>
3492 * </dl>
3493 *
3494 * @param klass
3495 * the target class type that {@code cast} will cast the items emitted by the source Observable
3496 * into before emitting them from the resulting Observable
3497 * @return an Observable that emits each item from the source Observable after converting it to the
3498 * specified type
3499 * @see <a href="http://reactivex.io/documentation/operators/map.html">ReactiveX operators documentation: Map</a>
3500 */
3501 public final <R> Observable<R> cast(final Class<R> klass) {
3502 return lift(new OperatorCast<T, R>(klass));
3503 }
3504
3505 /**
3506 * Collects items emitted by the source Observable into a single mutable data structure and returns an
3507 * Observable that emits this structure.
3508 * <p>
3509 * <img width="640" height="330" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/collect.png" alt="">
3510 * <p>
3511 * This is a simplified version of {@code reduce} that does not need to return the state on each pass.
3512 * <dl>
3513 * <dt><b>Backpressure Support:</b></dt>
3514 * <dd>This operator does not support backpressure because by intent it will receive all values and reduce
3515 * them to a single {@code onNext}.</dd>
3516 * <dt><b>Scheduler:</b></dt>
3517 * <dd>{@code collect} does not operate by default on a particular {@link Scheduler}.</dd>
3518 * </dl>
3519 *
3520 * @param stateFactory
3521 * the mutable data structure that will collect the items
3522 * @param collector
3523 * a function that accepts the {@code state} and an emitted item, and modifies {@code state}
3524 * accordingly
3525 * @return an Observable that emits the result of collecting the values emitted by the source Observable
3526 * into a single mutable data structure
3527 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
3528 */
3529 public final <R> Observable<R> collect(Func0<R> stateFactory, final Action2<R, ? super T> collector) {
3530 Func2<R, T, R> accumulator = new Func2<R, T, R>() {
3531
3532 @Override
3533 public final R call(R state, T value) {
3534 collector.call(state, value);
3535 return state;
3536 }
3537
3538 };
3539
3540 /*
3541 * Discussion and confirmation of implementation at
3542 * https://github.com/ReactiveX/RxJava/issues/423#issuecomment-27642532
3543 *
3544 * It should use last() not takeLast(1) since it needs to emit an error if the sequence is empty.
3545 */
3546 return lift(new OperatorScan<R, T>(stateFactory, accumulator)).last();
3547 }
3548
3549 /**
3550 * Returns a new Observable that emits items resulting from applying a function that you supply to each item
3551 * emitted by the source Observable, where that function returns an Observable, and then emitting the items
3552 * that result from concatinating those resulting Observables.
3553 * <p>
3554 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.png" alt="">
3555 * <dl>
3556 * <dt><b>Scheduler:</b></dt>
3557 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
3558 * </dl>
3559 *
3560 * @param func
3561 * a function that, when applied to an item emitted by the source Observable, returns an
3562 * Observable
3563 * @return an Observable that emits the result of applying the transformation function to each item emitted
3564 * by the source Observable and concatinating the Observables obtained from this transformation
3565 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3566 */
3567 public final <R> Observable<R> concatMap(Func1<? super T, ? extends Observable<? extends R>> func) {
3568 return concat(map(func));
3569 }
3570
3571 /**
3572 * Returns an Observable that emits the items emitted from the current Observable, then the next, one after
3573 * the other, without interleaving them.
3574 * <p>
3575 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.png" alt="">
3576 * <dl>
3577 * <dt><b>Scheduler:</b></dt>
3578 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
3579 * </dl>
3580 *
3581 * @param t1
3582 * an Observable to be concatenated after the current
3583 * @return an Observable that emits items emitted by the two source Observables, one after the other,
3584 * without interleaving them
3585 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
3586 */
3587 public final Observable<T> concatWith(Observable<? extends T> t1) {
3588 return concat(this, t1);
3589 }
3590
3591 /**
3592 * Returns an Observable that emits a Boolean that indicates whether the source Observable emitted a
3593 * specified item.
3594 * <p>
3595 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/contains.png" alt="">
3596 * <dl>
3597 * <dt><b>Scheduler:</b></dt>
3598 * <dd>{@code contains} does not operate by default on a particular {@link Scheduler}.</dd>
3599 * </dl>
3600 *
3601 * @param element
3602 * the item to search for in the emissions from the source Observable
3603 * @return an Observable that emits {@code true} if the specified item is emitted by the source Observable,
3604 * or {@code false} if the source Observable completes without emitting that item
3605 * @see <a href="http://reactivex.io/documentation/operators/contains.html">ReactiveX operators documentation: Contains</a>
3606 */
3607 public final Observable<Boolean> contains(final Object element) {
3608 return exists(new Func1<T, Boolean>() {
3609 @Override
3610 public final Boolean call(T t1) {
3611 return element == null ? t1 == null : element.equals(t1);
3612 }
3613 });
3614 }
3615
3616 /**
3617 * Returns an Observable that emits the count of the total number of items emitted by the source Observable.
3618 * <p>
3619 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/count.png" alt="">
3620 * <dl>
3621 * <dt><b>Backpressure Support:</b></dt>
3622 * <dd>This operator does not support backpressure because by intent it will receive all values and reduce
3623 * them to a single {@code onNext}.</dd>
3624 * <dt><b>Scheduler:</b></dt>
3625 * <dd>{@code count} does not operate by default on a particular {@link Scheduler}.</dd>
3626 * </dl>
3627 *
3628 * @return an Observable that emits a single item: the number of elements emitted by the source Observable
3629 * @see <a href="http://reactivex.io/documentation/operators/count.html">ReactiveX operators documentation: Count</a>
3630 * @see #countLong()
3631 */
3632 public final Observable<Integer> count() {
3633 return reduce(0, new Func2<Integer, T, Integer>() {
3634 @Override
3635 public final Integer call(Integer t1, T t2) {
3636 return t1 + 1;
3637 }
3638 });
3639 }
3640
3641 /**
3642 * Returns an Observable that counts the total number of items emitted by the source Observable and emits
3643 * this count as a 64-bit Long.
3644 * <p>
3645 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/longCount.png" alt="">
3646 * <dl>
3647 * <dt><b>Backpressure Support:</b></dt>
3648 * <dd>This operator does not support backpressure because by intent it will receive all values and reduce
3649 * them to a single {@code onNext}.</dd>
3650 * <dt><b>Scheduler:</b></dt>
3651 * <dd>{@code countLong} does not operate by default on a particular {@link Scheduler}.</dd>
3652 * </dl>
3653 *
3654 * @return an Observable that emits a single item: the number of items emitted by the source Observable as a
3655 * 64-bit Long item
3656 * @see <a href="http://reactivex.io/documentation/operators/count.html">ReactiveX operators documentation: Count</a>
3657 * @see #count()
3658 */
3659 public final Observable<Long> countLong() {
3660 return reduce(0L, new Func2<Long, T, Long>() {
3661 @Override
3662 public final Long call(Long t1, T t2) {
3663 return t1 + 1;
3664 }
3665 });
3666 }
3667
3668 /**
3669 * Returns an Observable that mirrors the source Observable, except that it drops items emitted by the
3670 * source Observable that are followed by another item within a computed debounce duration.
3671 * <p>
3672 * <img width="640" height="425" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/debounce.f.png" alt="">
3673 * <dl>
3674 * <dt><b>Backpressure Support:</b></dt>
3675 * <dd>This operator does not support backpressure as it uses the {@code debounceSelector} to mark
3676 * boundaries.</dd>
3677 * <dt><b>Scheduler:</b></dt>
3678 * <dd>This version of {@code debounce} does not operate by default on a particular {@link Scheduler}.</dd>
3679 * </dl>
3680 *
3681 * @param <U>
3682 * the debounce value type (ignored)
3683 * @param debounceSelector
3684 * function to retrieve a sequence that indicates the throttle duration for each item
3685 * @return an Observable that omits items emitted by the source Observable that are followed by another item
3686 * within a computed debounce duration
3687 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
3688 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
3689 */
3690 public final <U> Observable<T> debounce(Func1<? super T, ? extends Observable<U>> debounceSelector) {
3691 return lift(new OperatorDebounceWithSelector<T, U>(debounceSelector));
3692 }
3693
3694 /**
3695 * Returns an Observable that mirrors the source Observable, except that it drops items emitted by the
3696 * source Observable that are followed by newer items before a timeout value expires. The timer resets on
3697 * each emission.
3698 * <p>
3699 * <em>Note:</em> If items keep being emitted by the source Observable faster than the timeout then no items
3700 * will be emitted by the resulting Observable.
3701 * <p>
3702 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/debounce.png" alt="">
3703 * <p>
3704 * Information on debounce vs throttle:
3705 * <p>
3706 * <ul>
3707 * <li><a href="http://drupalmotion.com/article/debounce-and-throttle-visual-explanation">Debounce and Throttle: visual explanation</a></li>
3708 * <li><a href="http://unscriptable.com/2009/03/20/debouncing-javascript-methods/">Debouncing: javascript methods</a></li>
3709 * <li><a href="http://www.illyriad.co.uk/blog/index.php/2011/09/javascript-dont-spam-your-server-debounce-and-throttle/">Javascript - don't spam your server: debounce and throttle</a></li>
3710 * </ul>
3711 * <dl>
3712 * <dt><b>Backpressure Support:</b></dt>
3713 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
3714 * <dt><b>Scheduler:</b></dt>
3715 * <dd>This version of {@code debounce} operates by default on the {@code computation} {@link Scheduler}.</dd>
3716 * </dl>
3717 *
3718 * @param timeout
3719 * the time each item has to be "the most recent" of those emitted by the source Observable to
3720 * ensure that it's not dropped
3721 * @param unit
3722 * the {@link TimeUnit} for the timeout
3723 * @return an Observable that filters out items from the source Observable that are too quickly followed by
3724 * newer items
3725 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
3726 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
3727 * @see #throttleWithTimeout(long, TimeUnit)
3728 */
3729 public final Observable<T> debounce(long timeout, TimeUnit unit) {
3730 return debounce(timeout, unit, Schedulers.computation());
3731 }
3732
3733 /**
3734 * Returns an Observable that mirrors the source Observable, except that it drops items emitted by the
3735 * source Observable that are followed by newer items before a timeout value expires on a specified
3736 * Scheduler. The timer resets on each emission.
3737 * <p>
3738 * <em>Note:</em> If items keep being emitted by the source Observable faster than the timeout then no items
3739 * will be emitted by the resulting Observable.
3740 * <p>
3741 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/debounce.s.png" alt="">
3742 * <p>
3743 * Information on debounce vs throttle:
3744 * <p>
3745 * <ul>
3746 * <li><a href="http://drupalmotion.com/article/debounce-and-throttle-visual-explanation">Debounce and Throttle: visual explanation</a></li>
3747 * <li><a href="http://unscriptable.com/2009/03/20/debouncing-javascript-methods/">Debouncing: javascript methods</a></li>
3748 * <li><a href="http://www.illyriad.co.uk/blog/index.php/2011/09/javascript-dont-spam-your-server-debounce-and-throttle/">Javascript - don't spam your server: debounce and throttle</a></li>
3749 * </ul>
3750 * <dl>
3751 * <dt><b>Backpressure Support:</b></dt>
3752 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
3753 * <dt><b>Scheduler:</b></dt>
3754 * <dd>you specify which {@link Scheduler} this operator will use</dd>
3755 * </dl>
3756 *
3757 * @param timeout
3758 * the time each item has to be "the most recent" of those emitted by the source Observable to
3759 * ensure that it's not dropped
3760 * @param unit
3761 * the unit of time for the specified timeout
3762 * @param scheduler
3763 * the {@link Scheduler} to use internally to manage the timers that handle the timeout for each
3764 * item
3765 * @return an Observable that filters out items from the source Observable that are too quickly followed by
3766 * newer items
3767 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
3768 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
3769 * @see #throttleWithTimeout(long, TimeUnit, Scheduler)
3770 */
3771 public final Observable<T> debounce(long timeout, TimeUnit unit, Scheduler scheduler) {
3772 return lift(new OperatorDebounceWithTime<T>(timeout, unit, scheduler));
3773 }
3774
3775 /**
3776 * Returns an Observable that emits the items emitted by the source Observable or a specified default item
3777 * if the source Observable is empty.
3778 * <p>
3779 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/defaultIfEmpty.png" alt="">
3780 * <dl>
3781 * <dt><b>Scheduler:</b></dt>
3782 * <dd>{@code defaultIfEmpty} does not operate by default on a particular {@link Scheduler}.</dd>
3783 * </dl>
3784 *
3785 * @param defaultValue
3786 * the item to emit if the source Observable emits no items
3787 * @return an Observable that emits either the specified default item if the source Observable emits no
3788 * items, or the items emitted by the source Observable
3789 * @see <a href="http://reactivex.io/documentation/operators/defaultifempty.html">ReactiveX operators documentation: DefaultIfEmpty</a>
3790 */
3791 public final Observable<T> defaultIfEmpty(T defaultValue) {
3792 return lift(new OperatorDefaultIfEmpty<T>(defaultValue));
3793 }
3794
3795 /**
3796 * Returns an Observable that emits the items emitted by the source Observable or the items of an alternate
3797 * Observable if the source Observable is empty.
3798 * <p/>
3799 * <dl>
3800 * <dt><b>Scheduler:</b></dt>
3801 * <dd>{@code switchIfEmpty} does not operate by default on a particular {@link Scheduler}.</dd>
3802 * </dl>
3803 *
3804 * @param alternate
3805 * the alternate Observable to subscribe to if the source does not emit any items
3806 * @return an Observable that emits the items emitted by the source Observable or the items of an
3807 * alternate Observable if the source Observable is empty.
3808 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
3809 */
3810 @Experimental
3811 public final Observable<T> switchIfEmpty(Observable<? extends T> alternate) {
3812 return lift(new OperatorSwitchIfEmpty<T>(alternate));
3813 }
3814
3815 /**
3816 * Returns an Observable that delays the subscription to and emissions from the souce Observable via another
3817 * Observable on a per-item basis.
3818 * <p>
3819 * <img width="640" height="450" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.oo.png" alt="">
3820 * <p>
3821 * <em>Note:</em> the resulting Observable will immediately propagate any {@code onError} notification
3822 * from the source Observable.
3823 * <dl>
3824 * <dt><b>Scheduler:</b></dt>
3825 * <dd>This version of {@code delay} does not operate by default on a particular {@link Scheduler}.</dd>
3826 * </dl>
3827 *
3828 * @param <U>
3829 * the subscription delay value type (ignored)
3830 * @param <V>
3831 * the item delay value type (ignored)
3832 * @param subscriptionDelay
3833 * a function that returns an Observable that triggers the subscription to the source Observable
3834 * once it emits any item
3835 * @param itemDelay
3836 * a function that returns an Observable for each item emitted by the source Observable, which is
3837 * then used to delay the emission of that item by the resulting Observable until the Observable
3838 * returned from {@code itemDelay} emits an item
3839 * @return an Observable that delays the subscription and emissions of the source Observable via another
3840 * Observable on a per-item basis
3841 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
3842 */
3843 public final <U, V> Observable<T> delay(
3844 Func0<? extends Observable<U>> subscriptionDelay,
3845 Func1<? super T, ? extends Observable<V>> itemDelay) {
3846 return delaySubscription(subscriptionDelay).lift(new OperatorDelayWithSelector<T, V>(this, itemDelay));
3847 }
3848
3849 /**
3850 * Returns an Observable that delays the emissions of the source Observable via another Observable on a
3851 * per-item basis.
3852 * <p>
3853 * <img width="640" height="450" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.o.png" alt="">
3854 * <p>
3855 * <em>Note:</em> the resulting Observable will immediately propagate any {@code onError} notification
3856 * from the source Observable.
3857 * <dl>
3858 * <dt><b>Scheduler:</b></dt>
3859 * <dd>This version of {@code delay} does not operate by default on a particular {@link Scheduler}.</dd>
3860 * </dl>
3861 *
3862 * @param <U>
3863 * the item delay value type (ignored)
3864 * @param itemDelay
3865 * a function that returns an Observable for each item emitted by the source Observable, which is
3866 * then used to delay the emission of that item by the resulting Observable until the Observable
3867 * returned from {@code itemDelay} emits an item
3868 * @return an Observable that delays the emissions of the source Observable via another Observable on a
3869 * per-item basis
3870 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
3871 */
3872 public final <U> Observable<T> delay(Func1<? super T, ? extends Observable<U>> itemDelay) {
3873 return lift(new OperatorDelayWithSelector<T, U>(this, itemDelay));
3874 }
3875
3876 /**
3877 * Returns an Observable that emits the items emitted by the source Observable shifted forward in time by a
3878 * specified delay. Error notifications from the source Observable are not delayed.
3879 * <p>
3880 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.png" alt="">
3881 * <dl>
3882 * <dt><b>Scheduler:</b></dt>
3883 * <dd>This version of {@code delay} operates by default on the {@code compuation} {@link Scheduler}.</dd>
3884 * </dl>
3885 *
3886 * @param delay
3887 * the delay to shift the source by
3888 * @param unit
3889 * the {@link TimeUnit} in which {@code period} is defined
3890 * @return the source Observable shifted in time by the specified delay
3891 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
3892 */
3893 public final Observable<T> delay(long delay, TimeUnit unit) {
3894 return delay(delay, unit, Schedulers.computation());
3895 }
3896
3897 /**
3898 * Returns an Observable that emits the items emitted by the source Observable shifted forward in time by a
3899 * specified delay. Error notifications from the source Observable are not delayed.
3900 * <p>
3901 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.s.png" alt="">
3902 * <dl>
3903 * <dt><b>Scheduler:</b></dt>
3904 * <dd>you specify which {@link Scheduler} this operator will use</dd>
3905 * </dl>
3906 *
3907 * @param delay
3908 * the delay to shift the source by
3909 * @param unit
3910 * the time unit of {@code delay}
3911 * @param scheduler
3912 * the {@link Scheduler} to use for delaying
3913 * @return the source Observable shifted in time by the specified delay
3914 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
3915 */
3916 public final Observable<T> delay(long delay, TimeUnit unit, Scheduler scheduler) {
3917 return lift(new OperatorDelay<T>(this, delay, unit, scheduler));
3918 }
3919
3920 /**
3921 * Returns an Observable that delays the subscription to the source Observable by a given amount of time.
3922 * <p>
3923 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.png" alt="">
3924 * <dl>
3925 * <dt><b>Scheduler:</b></dt>
3926 * <dd>This version of {@code delay} operates by default on the {@code compuation} {@link Scheduler}.</dd>
3927 * </dl>
3928 *
3929 * @param delay
3930 * the time to delay the subscription
3931 * @param unit
3932 * the time unit of {@code delay}
3933 * @return an Observable that delays the subscription to the source Observable by the given amount
3934 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
3935 */
3936 public final Observable<T> delaySubscription(long delay, TimeUnit unit) {
3937 return delaySubscription(delay, unit, Schedulers.computation());
3938 }
3939
3940 /**
3941 * Returns an Observable that delays the subscription to the source Observable by a given amount of time,
3942 * both waiting and subscribing on a given Scheduler.
3943 * <p>
3944 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.s.png" alt="">
3945 * <dl>
3946 * <dt><b>Scheduler:</b></dt>
3947 * <dd>you specify which {@link Scheduler} this operator will use</dd>
3948 * </dl>
3949 *
3950 * @param delay
3951 * the time to delay the subscription
3952 * @param unit
3953 * the time unit of {@code delay}
3954 * @param scheduler
3955 * the Scheduler on which the waiting and subscription will happen
3956 * @return an Observable that delays the subscription to the source Observable by a given
3957 * amount, waiting and subscribing on the given Scheduler
3958 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
3959 */
3960 public final Observable<T> delaySubscription(long delay, TimeUnit unit, Scheduler scheduler) {
3961 return create(new OnSubscribeDelaySubscription<T>(this, delay, unit, scheduler));
3962 }
3963
3964 /**
3965 * Returns an Observable that delays the subscription to the source Observable until a second Observable
3966 * emits an item.
3967 * <p>
3968 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.o.png" alt="">
3969 * <dl>
3970 * <dt><b>Scheduler:</b></dt>
3971 * <dd>This version of {@code delay} operates by default on the {@code compuation} {@link Scheduler}.</dd>
3972 * </dl>
3973 *
3974 * @param subscriptionDelay
3975 * a function that returns an Observable that triggers the subscription to the source Observable
3976 * once it emits any item
3977 * @return an Observable that delays the subscription to the source Observable until the Observable returned
3978 * by {@code subscriptionDelay} emits an item
3979 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
3980 */
3981 public final <U> Observable<T> delaySubscription(Func0<? extends Observable<U>> subscriptionDelay) {
3982 return create(new OnSubscribeDelaySubscriptionWithSelector<T, U>(this, subscriptionDelay));
3983 }
3984
3985 /**
3986 * Returns an Observable that reverses the effect of {@link #materialize materialize} by transforming the
3987 * {@link Notification} objects emitted by the source Observable into the items or notifications they
3988 * represent.
3989 * <p>
3990 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/dematerialize.png" alt="">
3991 * <dl>
3992 * <dt><b>Scheduler:</b></dt>
3993 * <dd>{@code dematerialize} does not operate by default on a particular {@link Scheduler}.</dd>
3994 * </dl>
3995 *
3996 * @return an Observable that emits the items and notifications embedded in the {@link Notification} objects
3997 * emitted by the source Observable
3998 * @throws OnErrorNotImplementedException
3999 * if the source Observable is not of type {@code Observable<Notification<T>>}
4000 * @see <a href="http://reactivex.io/documentation/operators/materialize-dematerialize.html">ReactiveX operators documentation: Dematerialize</a>
4001 */
4002 @SuppressWarnings({"unchecked"})
4003 public final <T2> Observable<T2> dematerialize() {
4004 return lift(OperatorDematerialize.instance());
4005 }
4006
4007 /**
4008 * Returns an Observable that emits all items emitted by the source Observable that are distinct.
4009 * <p>
4010 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.png" alt="">
4011 * <dl>
4012 * <dt><b>Scheduler:</b></dt>
4013 * <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
4014 * </dl>
4015 *
4016 * @return an Observable that emits only those items emitted by the source Observable that are distinct from
4017 * each other
4018 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
4019 */
4020 public final Observable<T> distinct() {
4021 return lift(new OperatorDistinct<T, T>(UtilityFunctions.<T>identity()));
4022 }
4023
4024 /**
4025 * Returns an Observable that emits all items emitted by the source Observable that are distinct according
4026 * to a key selector function.
4027 * <p>
4028 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.key.png" alt="">
4029 * <dl>
4030 * <dt><b>Scheduler:</b></dt>
4031 * <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
4032 * </dl>
4033 *
4034 * @param keySelector
4035 * a function that projects an emitted item to a key value that is used to decide whether an item
4036 * is distinct from another one or not
4037 * @return an Observable that emits those items emitted by the source Observable that have distinct keys
4038 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
4039 */
4040 public final <U> Observable<T> distinct(Func1<? super T, ? extends U> keySelector) {
4041 return lift(new OperatorDistinct<T, U>(keySelector));
4042 }
4043
4044 /**
4045 * Returns an Observable that emits all items emitted by the source Observable that are distinct from their
4046 * immediate predecessors.
4047 * <p>
4048 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.png" alt="">
4049 * <dl>
4050 * <dt><b>Scheduler:</b></dt>
4051 * <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
4052 * </dl>
4053 *
4054 * @return an Observable that emits those items from the source Observable that are distinct from their
4055 * immediate predecessors
4056 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
4057 */
4058 public final Observable<T> distinctUntilChanged() {
4059 return lift(new OperatorDistinctUntilChanged<T, T>(UtilityFunctions.<T>identity()));
4060 }
4061
4062 /**
4063 * Returns an Observable that emits all items emitted by the source Observable that are distinct from their
4064 * immediate predecessors, according to a key selector function.
4065 * <p>
4066 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.key.png" alt="">
4067 * <dl>
4068 * <dt><b>Scheduler:</b></dt>
4069 * <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
4070 * </dl>
4071 *
4072 * @param keySelector
4073 * a function that projects an emitted item to a key value that is used to decide whether an item
4074 * is distinct from another one or not
4075 * @return an Observable that emits those items from the source Observable whose keys are distinct from
4076 * those of their immediate predecessors
4077 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
4078 */
4079 public final <U> Observable<T> distinctUntilChanged(Func1<? super T, ? extends U> keySelector) {
4080 return lift(new OperatorDistinctUntilChanged<T, U>(keySelector));
4081 }
4082
4083 /**
4084 * Modifies the source Observable so that it invokes an action when it calls {@code onCompleted}.
4085 * <p>
4086 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnCompleted.png" alt="">
4087 * <dl>
4088 * <dt><b>Scheduler:</b></dt>
4089 * <dd>{@code doOnCompleted} does not operate by default on a particular {@link Scheduler}.</dd>
4090 * </dl>
4091 *
4092 * @param onCompleted
4093 * the action to invoke when the source Observable calls {@code onCompleted}
4094 * @return the source Observable with the side-effecting behavior applied
4095 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4096 */
4097 public final Observable<T> doOnCompleted(final Action0 onCompleted) {
4098 Observer<T> observer = new Observer<T>() {
4099 @Override
4100 public final void onCompleted() {
4101 onCompleted.call();
4102 }
4103
4104 @Override
4105 public final void onError(Throwable e) {
4106 }
4107
4108 @Override
4109 public final void onNext(T args) {
4110 }
4111
4112 };
4113
4114 return lift(new OperatorDoOnEach<T>(observer));
4115 }
4116
4117 /**
4118 * Modifies the source Observable so that it invokes an action for each item it emits.
4119 * <p>
4120 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnEach.png" alt="">
4121 * <dl>
4122 * <dt><b>Scheduler:</b></dt>
4123 * <dd>{@code doOnEach} does not operate by default on a particular {@link Scheduler}.</dd>
4124 * </dl>
4125 *
4126 * @param onNotification
4127 * the action to invoke for each item emitted by the source Observable
4128 * @return the source Observable with the side-effecting behavior applied
4129 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4130 */
4131 public final Observable<T> doOnEach(final Action1<Notification<? super T>> onNotification) {
4132 Observer<T> observer = new Observer<T>() {
4133 @Override
4134 public final void onCompleted() {
4135 onNotification.call(Notification.createOnCompleted());
4136 }
4137
4138 @Override
4139 public final void onError(Throwable e) {
4140 onNotification.call(Notification.createOnError(e));
4141 }
4142
4143 @Override
4144 public final void onNext(T v) {
4145 onNotification.call(Notification.createOnNext(v));
4146 }
4147
4148 };
4149
4150 return lift(new OperatorDoOnEach<T>(observer));
4151 }
4152
4153 /**
4154 * Modifies the source Observable so that it notifies an Observer for each item it emits.
4155 * <p>
4156 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnEach.png" alt="">
4157 * <dl>
4158 * <dt><b>Scheduler:</b></dt>
4159 * <dd>{@code doOnEach} does not operate by default on a particular {@link Scheduler}.</dd>
4160 * </dl>
4161 *
4162 * @param observer
4163 * the action to invoke for each item emitted by the source Observable
4164 * @return the source Observable with the side-effecting behavior applied
4165 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4166 */
4167 public final Observable<T> doOnEach(Observer<? super T> observer) {
4168 return lift(new OperatorDoOnEach<T>(observer));
4169 }
4170
4171 /**
4172 * Modifies the source Observable so that it invokes an action if it calls {@code onError}.
4173 * <p>
4174 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnError.png" alt="">
4175 * <dl>
4176 * <dt><b>Scheduler:</b></dt>
4177 * <dd>{@code doOnError} does not operate by default on a particular {@link Scheduler}.</dd>
4178 * </dl>
4179 *
4180 * @param onError
4181 * the action to invoke if the source Observable calls {@code onError}
4182 * @return the source Observable with the side-effecting behavior applied
4183 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4184 */
4185 public final Observable<T> doOnError(final Action1<Throwable> onError) {
4186 Observer<T> observer = new Observer<T>() {
4187 @Override
4188 public final void onCompleted() {
4189 }
4190
4191 @Override
4192 public final void onError(Throwable e) {
4193 onError.call(e);
4194 }
4195
4196 @Override
4197 public final void onNext(T args) {
4198 }
4199
4200 };
4201
4202 return lift(new OperatorDoOnEach<T>(observer));
4203 }
4204
4205 /**
4206 * Modifies the source Observable so that it invokes an action when it calls {@code onNext}.
4207 * <p>
4208 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnNext.png" alt="">
4209 * <dl>
4210 * <dt><b>Scheduler:</b></dt>
4211 * <dd>{@code doOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
4212 * </dl>
4213 *
4214 * @param onNext
4215 * the action to invoke when the source Observable calls {@code onNext}
4216 * @return the source Observable with the side-effecting behavior applied
4217 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4218 */
4219 public final Observable<T> doOnNext(final Action1<? super T> onNext) {
4220 Observer<T> observer = new Observer<T>() {
4221 @Override
4222 public final void onCompleted() {
4223 }
4224
4225 @Override
4226 public final void onError(Throwable e) {
4227 }
4228
4229 @Override
4230 public final void onNext(T args) {
4231 onNext.call(args);
4232 }
4233
4234 };
4235
4236 return lift(new OperatorDoOnEach<T>(observer));
4237 }
4238
4239 /**
4240 * Modifies the source {@code Observable} so that it invokes the given action when it receives a request for
4241 * more items.
4242 * <dl>
4243 * <dt><b>Scheduler:</b></dt>
4244 * <dd>{@code doOnRequest} does not operate by default on a particular {@link Scheduler}.</dd>
4245 * </dl>
4246 *
4247 * @param onRequest
4248 * the action that gets called when an observer requests items from this {@code Observable}
4249 * @return the source {@code Observable} modified so as to call this Action when appropriate
4250 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4251 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
4252 */
4253 @Beta
4254 public final Observable<T> doOnRequest(final Action1<Long> onRequest) {
4255 return lift(new OperatorDoOnRequest<T>(onRequest));
4256 }
4257
4258 /**
4259 * Modifies the source {@code Observable} so that it invokes the given action when it is subscribed from
4260 * its subscribers. Each subscription will result in an invocation of the given action except when the
4261 * source {@code Observable} is reference counted, in which case the source {@code Observable} will invoke
4262 * the given action for the first subscription.
4263 * <p>
4264 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnSubscribe.png" alt="">
4265 * <dl>
4266 * <dt><b>Scheduler:</b></dt>
4267 * <dd>{@code doOnSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
4268 * </dl>
4269 *
4270 * @param subscribe
4271 * the action that gets called when an observer subscribes to this {@code Observable}
4272 * @return the source {@code Observable} modified so as to call this Action when appropriate
4273 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4274 */
4275 public final Observable<T> doOnSubscribe(final Action0 subscribe) {
4276 return lift(new OperatorDoOnSubscribe<T>(subscribe));
4277 }
4278
4279 /**
4280 * Modifies the source Observable so that it invokes an action when it calls {@code onCompleted} or
4281 * {@code onError}.
4282 * <p>
4283 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnTerminate.png" alt="">
4284 * <p>
4285 * This differs from {@code finallyDo} in that this happens <em>before</em> the {@code onCompleted} or
4286 * {@code onError} notification.
4287 * <dl>
4288 * <dt><b>Scheduler:</b></dt>
4289 * <dd>{@code doOnTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
4290 * </dl>
4291 *
4292 * @param onTerminate
4293 * the action to invoke when the source Observable calls {@code onCompleted} or {@code onError}
4294 * @return the source Observable with the side-effecting behavior applied
4295 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4296 * @see #finallyDo(Action0)
4297 */
4298 public final Observable<T> doOnTerminate(final Action0 onTerminate) {
4299 Observer<T> observer = new Observer<T>() {
4300 @Override
4301 public final void onCompleted() {
4302 onTerminate.call();
4303 }
4304
4305 @Override
4306 public final void onError(Throwable e) {
4307 onTerminate.call();
4308 }
4309
4310 @Override
4311 public final void onNext(T args) {
4312 }
4313
4314 };
4315
4316 return lift(new OperatorDoOnEach<T>(observer));
4317 }
4318
4319 /**
4320 * Modifies the source {@code Observable} so that it invokes the given action when it is unsubscribed from
4321 * its subscribers. Each un-subscription will result in an invocation of the given action except when the
4322 * source {@code Observable} is reference counted, in which case the source {@code Observable} will invoke
4323 * the given action for the very last un-subscription.
4324 * <p>
4325 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnUnsubscribe.png" alt="">
4326 * <dl>
4327 * <dt><b>Scheduler:</b></dt>
4328 * <dd>{@code doOnUnsubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
4329 * </dl>
4330 *
4331 * @param unsubscribe
4332 * the action that gets called when this {@code Observable} is unsubscribed
4333 * @return the source {@code Observable} modified so as to call this Action when appropriate
4334 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4335 */
4336 public final Observable<T> doOnUnsubscribe(final Action0 unsubscribe) {
4337 return lift(new OperatorDoOnUnsubscribe<T>(unsubscribe));
4338 }
4339
4340 /**
4341 * Returns an Observable that emits the single item at a specified index in a sequence of emissions from a
4342 * source Observbable.
4343 * <p>
4344 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAt.png" alt="">
4345 * <dl>
4346 * <dt><b>Scheduler:</b></dt>
4347 * <dd>{@code elementAt} does not operate by default on a particular {@link Scheduler}.</dd>
4348 * </dl>
4349 *
4350 * @param index
4351 * the zero-based index of the item to retrieve
4352 * @return an Observable that emits a single item: the item at the specified position in the sequence of
4353 * those emitted by the source Observable
4354 * @throws IndexOutOfBoundsException
4355 * if {@code index} is greater than or equal to the number of items emitted by the source
4356 * Observable, or
4357 * if {@code index} is less than 0
4358 * @see <a href="http://reactivex.io/documentation/operators/elementat.html">ReactiveX operators documentation: ElementAt</a>
4359 */
4360 public final Observable<T> elementAt(int index) {
4361 return lift(new OperatorElementAt<T>(index));
4362 }
4363
4364 /**
4365 * Returns an Observable that emits the item found at a specified index in a sequence of emissions from a
4366 * source Observable, or a default item if that index is out of range.
4367 * <p>
4368 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtOrDefault.png" alt="">
4369 * <dl>
4370 * <dt><b>Scheduler:</b></dt>
4371 * <dd>{@code elementAtOrDefault} does not operate by default on a particular {@link Scheduler}.</dd>
4372 * </dl>
4373 *
4374 * @param index
4375 * the zero-based index of the item to retrieve
4376 * @param defaultValue
4377 * the default item
4378 * @return an Observable that emits the item at the specified position in the sequence emitted by the source
4379 * Observable, or the default item if that index is outside the bounds of the source sequence
4380 * @throws IndexOutOfBoundsException
4381 * if {@code index} is less than 0
4382 * @see <a href="http://reactivex.io/documentation/operators/elementat.html">ReactiveX operators documentation: ElementAt</a>
4383 */
4384 public final Observable<T> elementAtOrDefault(int index, T defaultValue) {
4385 return lift(new OperatorElementAt<T>(index, defaultValue));
4386 }
4387
4388 /**
4389 * Returns an Observable that emits {@code true} if any item emitted by the source Observable satisfies a
4390 * specified condition, otherwise {@code false}. <em>Note:</em> this always emits {@code false} if the
4391 * source Observable is empty.
4392 * <p>
4393 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/exists.png" alt="">
4394 * <p>
4395 * In Rx.Net this is the {@code any} Observer but we renamed it in RxJava to better match Java naming
4396 * idioms.
4397 * <dl>
4398 * <dt><b>Scheduler:</b></dt>
4399 * <dd>{@code exists} does not operate by default on a particular {@link Scheduler}.</dd>
4400 * </dl>
4401 *
4402 * @param predicate
4403 * the condition to test items emitted by the source Observable
4404 * @return an Observable that emits a Boolean that indicates whether any item emitted by the source
4405 * Observable satisfies the {@code predicate}
4406 * @see <a href="http://reactivex.io/documentation/operators/contains.html">ReactiveX operators documentation: Contains</a>
4407 */
4408 public final Observable<Boolean> exists(Func1<? super T, Boolean> predicate) {
4409 return lift(new OperatorAny<T>(predicate, false));
4410 }
4411
4412 /**
4413 * Filters items emitted by an Observable by only emitting those that satisfy a specified predicate.
4414 * <p>
4415 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/filter.png" alt="">
4416 * <dl>
4417 * <dt><b>Scheduler:</b></dt>
4418 * <dd>{@code filter} does not operate by default on a particular {@link Scheduler}.</dd>
4419 * </dl>
4420 *
4421 * @param predicate
4422 * a function that evaluates each item emitted by the source Observable, returning {@code true}
4423 * if it passes the filter
4424 * @return an Observable that emits only those items emitted by the source Observable that the filter
4425 * evaluates as {@code true}
4426 * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
4427 */
4428 public final Observable<T> filter(Func1<? super T, Boolean> predicate) {
4429 return lift(new OperatorFilter<T>(predicate));
4430 }
4431
4432 /**
4433 * Registers an {@link Action0} to be called when this Observable invokes either
4434 * {@link Observer#onCompleted onCompleted} or {@link Observer#onError onError}.
4435 * <p>
4436 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/finallyDo.png" alt="">
4437 * <dl>
4438 * <dt><b>Scheduler:</b></dt>
4439 * <dd>{@code finallyDo} does not operate by default on a particular {@link Scheduler}.</dd>
4440 * </dl>
4441 *
4442 * @param action
4443 * an {@link Action0} to be invoked when the source Observable finishes
4444 * @return an Observable that emits the same items as the source Observable, then invokes the
4445 * {@link Action0}
4446 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
4447 * @see #doOnTerminate(Action0)
4448 */
4449 public final Observable<T> finallyDo(Action0 action) {
4450 return lift(new OperatorFinally<T>(action));
4451 }
4452
4453 /**
4454 * Returns an Observable that emits only the very first item emitted by the source Observable, or notifies
4455 * of an {@code NoSuchElementException} if the source Observable is empty.
4456 * <p>
4457 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/first.png" alt="">
4458 * <dl>
4459 * <dt><b>Scheduler:</b></dt>
4460 * <dd>{@code first} does not operate by default on a particular {@link Scheduler}.</dd>
4461 * </dl>
4462 *
4463 * @return an Observable that emits only the very first item emitted by the source Observable, or raises an
4464 * {@code NoSuchElementException} if the source Observable is empty
4465 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
4466 */
4467 public final Observable<T> first() {
4468 return take(1).single();
4469 }
4470
4471 /**
4472 * Returns an Observable that emits only the very first item emitted by the source Observable that satisfies
4473 * a specified condition, or notifies of an {@code NoSuchElementException} if no such items are emitted.
4474 * <p>
4475 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstN.png" alt="">
4476 * <dl>
4477 * <dt><b>Scheduler:</b></dt>
4478 * <dd>{@code first} does not operate by default on a particular {@link Scheduler}.</dd>
4479 * </dl>
4480 *
4481 * @param predicate
4482 * the condition that an item emitted by the source Observable has to satisfy
4483 * @return an Observable that emits only the very first item emitted by the source Observable that satisfies
4484 * the {@code predicate}, or raises an {@code NoSuchElementException} if no such items are emitted
4485 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
4486 */
4487 public final Observable<T> first(Func1<? super T, Boolean> predicate) {
4488 return takeFirst(predicate).single();
4489 }
4490
4491 /**
4492 * Returns an Observable that emits only the very first item emitted by the source Observable, or a default
4493 * item if the source Observable completes without emitting anything.
4494 * <p>
4495 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrDefault.png" alt="">
4496 * <dl>
4497 * <dt><b>Scheduler:</b></dt>
4498 * <dd>{@code firstOrDefault} does not operate by default on a particular {@link Scheduler}.</dd>
4499 * </dl>
4500 *
4501 * @param defaultValue
4502 * the default item to emit if the source Observable doesn't emit anything
4503 * @return an Observable that emits only the very first item from the source, or a default item if the
4504 * source Observable completes without emitting any items
4505 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
4506 */
4507 public final Observable<T> firstOrDefault(T defaultValue) {
4508 return take(1).singleOrDefault(defaultValue);
4509 }
4510
4511 /**
4512 * Returns an Observable that emits only the very first item emitted by the source Observable that satisfies
4513 * a specified condition, or a default item if the source Observable emits no such items.
4514 * <p>
4515 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrDefaultN.png" alt="">
4516 * <dl>
4517 * <dt><b>Scheduler:</b></dt>
4518 * <dd>{@code firstOrDefault} does not operate by default on a particular {@link Scheduler}.</dd>
4519 * </dl>
4520 *
4521 * @param predicate
4522 * the condition any item emitted by the source Observable has to satisfy
4523 * @param defaultValue
4524 * the default item to emit if the source Observable doesn't emit anything that satisfies the
4525 * {@code predicate}
4526 * @return an Observable that emits only the very first item emitted by the source Observable that satisfies
4527 * the {@code predicate}, or a default item if the source Observable emits no such items
4528 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
4529 */
4530 public final Observable<T> firstOrDefault(T defaultValue, Func1<? super T, Boolean> predicate) {
4531 return takeFirst(predicate).singleOrDefault(defaultValue);
4532 }
4533
4534 /**
4535 * Returns an Observable that emits items based on applying a function that you supply to each item emitted
4536 * by the source Observable, where that function returns an Observable, and then merging those resulting
4537 * Observables and emitting the results of this merger.
4538 * <p>
4539 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMap.png" alt="">
4540 * <dl>
4541 * <dt><b>Scheduler:</b></dt>
4542 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
4543 * </dl>
4544 *
4545 * @param func
4546 * a function that, when applied to an item emitted by the source Observable, returns an
4547 * Observable
4548 * @return an Observable that emits the result of applying the transformation function to each item emitted
4549 * by the source Observable and merging the results of the Observables obtained from this
4550 * transformation
4551 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
4552 */
4553 public final <R> Observable<R> flatMap(Func1<? super T, ? extends Observable<? extends R>> func) {
4554 return merge(map(func));
4555 }
4556
4557 /**
4558 * Returns an Observable that emits items based on applying a function that you supply to each item emitted
4559 * by the source Observable, where that function returns an Observable, and then merging those resulting
4560 * Observables and emitting the results of this merger, while limiting the maximum number of concurrent
4561 * subscriptions to these Observables.
4562 * <p>
4563 * <!-- <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMap.png" alt=""> -->
4564 * <dl>
4565 * <dt><b>Scheduler:</b></dt>
4566 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
4567 * </dl>
4568 *
4569 * @param func
4570 * a function that, when applied to an item emitted by the source Observable, returns an
4571 * Observable
4572 * @param maxConcurrent
4573 * the maximum number of Observables that may be subscribed to concurrently
4574 * @return an Observable that emits the result of applying the transformation function to each item emitted
4575 * by the source Observable and merging the results of the Observables obtained from this
4576 * transformation
4577 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
4578 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
4579 */
4580 @Beta
4581 public final <R> Observable<R> flatMap(Func1<? super T, ? extends Observable<? extends R>> func, int maxConcurrent) {
4582 return merge(map(func), maxConcurrent);
4583 }
4584
4585 /**
4586 * Returns an Observable that applies a function to each item emitted or notification raised by the source
4587 * Observable and then flattens the Observables returned from these functions and emits the resulting items.
4588 * <p>
4589 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.nce.png" alt="">
4590 * <dl>
4591 * <dt><b>Scheduler:</b></dt>
4592 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
4593 * </dl>
4594 *
4595 * @param <R>
4596 * the result type
4597 * @param onNext
4598 * a function that returns an Observable to merge for each item emitted by the source Observable
4599 * @param onError
4600 * a function that returns an Observable to merge for an onError notification from the source
4601 * Observable
4602 * @param onCompleted
4603 * a function that returns an Observable to merge for an onCompleted notification from the source
4604 * Observable
4605 * @return an Observable that emits the results of merging the Observables returned from applying the
4606 * specified functions to the emissions and notifications of the source Observable
4607 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
4608 */
4609 public final <R> Observable<R> flatMap(
4610 Func1<? super T, ? extends Observable<? extends R>> onNext,
4611 Func1<? super Throwable, ? extends Observable<? extends R>> onError,
4612 Func0<? extends Observable<? extends R>> onCompleted) {
4613 return merge(mapNotification(onNext, onError, onCompleted));
4614 }
4615 /**
4616 * Returns an Observable that applies a function to each item emitted or notification raised by the source
4617 * Observable and then flattens the Observables returned from these functions and emits the resulting items,
4618 * while limiting the maximum number of concurrent subscriptions to these Observables.
4619 * <p>
4620 * <!-- <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.nce.png" alt=""> -->
4621 * <dl>
4622 * <dt><b>Scheduler:</b></dt>
4623 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
4624 * </dl>
4625 *
4626 * @param <R>
4627 * the result type
4628 * @param onNext
4629 * a function that returns an Observable to merge for each item emitted by the source Observable
4630 * @param onError
4631 * a function that returns an Observable to merge for an onError notification from the source
4632 * Observable
4633 * @param onCompleted
4634 * a function that returns an Observable to merge for an onCompleted notification from the source
4635 * Observable
4636 * @param maxConcurrent
4637 * the maximum number of Observables that may be subscribed to concurrently
4638 * @return an Observable that emits the results of merging the Observables returned from applying the
4639 * specified functions to the emissions and notifications of the source Observable
4640 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
4641 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
4642 */
4643 @Beta
4644 public final <R> Observable<R> flatMap(
4645 Func1<? super T, ? extends Observable<? extends R>> onNext,
4646 Func1<? super Throwable, ? extends Observable<? extends R>> onError,
4647 Func0<? extends Observable<? extends R>> onCompleted, int maxConcurrent) {
4648 return merge(mapNotification(onNext, onError, onCompleted), maxConcurrent);
4649 }
4650
4651 /**
4652 * Returns an Observable that emits the results of a specified function to the pair of values emitted by the
4653 * source Observable and a specified collection Observable.
4654 * <p>
4655 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.png" alt="">
4656 * <dl>
4657 * <dt><b>Scheduler:</b></dt>
4658 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
4659 * </dl>
4660 *
4661 * @param <U>
4662 * the type of items emitted by the collection Observable
4663 * @param <R>
4664 * the type of items emitted by the resulting Observable
4665 * @param collectionSelector
4666 * a function that returns an Observable for each item emitted by the source Observable
4667 * @param resultSelector
4668 * a function that combines one item emitted by each of the source and collection Observables and
4669 * returns an item to be emitted by the resulting Observable
4670 * @return an Observable that emits the results of applying a function to a pair of values emitted by the
4671 * source Observable and the collection Observable
4672 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
4673 */
4674 public final <U, R> Observable<R> flatMap(final Func1<? super T, ? extends Observable<? extends U>> collectionSelector,
4675 final Func2<? super T, ? super U, ? extends R> resultSelector) {
4676 return merge(lift(new OperatorMapPair<T, U, R>(collectionSelector, resultSelector)));
4677 }
4678 /**
4679 * Returns an Observable that emits the results of a specified function to the pair of values emitted by the
4680 * source Observable and a specified collection Observable, while limiting the maximum number of concurrent
4681 * subscriptions to these Observables.
4682 * <p>
4683 * <!-- <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.png" alt=""> -->
4684 * <dl>
4685 * <dt><b>Scheduler:</b></dt>
4686 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
4687 * </dl>
4688 *
4689 * @param <U>
4690 * the type of items emitted by the collection Observable
4691 * @param <R>
4692 * the type of items emitted by the resulting Observable
4693 * @param collectionSelector
4694 * a function that returns an Observable for each item emitted by the source Observable
4695 * @param resultSelector
4696 * a function that combines one item emitted by each of the source and collection Observables and
4697 * returns an item to be emitted by the resulting Observable
4698 * @param maxConcurrent
4699 * the maximum number of Observables that may be subscribed to concurrently
4700 * @return an Observable that emits the results of applying a function to a pair of values emitted by the
4701 * source Observable and the collection Observable
4702 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
4703 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
4704 */
4705 @Beta
4706 public final <U, R> Observable<R> flatMap(final Func1<? super T, ? extends Observable<? extends U>> collectionSelector,
4707 final Func2<? super T, ? super U, ? extends R> resultSelector, int maxConcurrent) {
4708 return merge(lift(new OperatorMapPair<T, U, R>(collectionSelector, resultSelector)), maxConcurrent);
4709 }
4710
4711 /**
4712 * Returns an Observable that merges each item emitted by the source Observable with the values in an
4713 * Iterable corresponding to that item that is generated by a selector.
4714 * <p>
4715 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMapIterable.png" alt="">
4716 * <dl>
4717 * <dt><b>Scheduler:</b></dt>
4718 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
4719 * </dl>
4720 *
4721 * @param <R>
4722 * the type of item emitted by the resulting Observable
4723 * @param collectionSelector
4724 * a function that returns an Iterable sequence of values for when given an item emitted by the
4725 * source Observable
4726 * @return an Observable that emits the results of merging the items emitted by the source Observable with
4727 * the values in the Iterables corresponding to those items, as generated by {@code collectionSelector}
4728 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
4729 */
4730 public final <R> Observable<R> flatMapIterable(Func1<? super T, ? extends Iterable<? extends R>> collectionSelector) {
4731 return merge(map(OperatorMapPair.convertSelector(collectionSelector)));
4732 }
4733
4734 /**
4735 * Returns an Observable that emits the results of applying a function to the pair of values from the source
4736 * Observable and an Iterable corresponding to that item that is generated by a selector.
4737 * <p>
4738 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMapIterable.r.png" alt="">
4739 * <dl>
4740 * <dt><b>Scheduler:</b></dt>
4741 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
4742 * </dl>
4743 *
4744 * @param <U>
4745 * the collection element type
4746 * @param <R>
4747 * the type of item emited by the resulting Observable
4748 * @param collectionSelector
4749 * a function that returns an Iterable sequence of values for each item emitted by the source
4750 * Observable
4751 * @param resultSelector
4752 * a function that returns an item based on the item emitted by the source Observable and the
4753 * Iterable returned for that item by the {@code collectionSelector}
4754 * @return an Observable that emits the items returned by {@code resultSelector} for each item in the source
4755 * Observable
4756 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
4757 */
4758 public final <U, R> Observable<R> flatMapIterable(Func1<? super T, ? extends Iterable<? extends U>> collectionSelector,
4759 Func2<? super T, ? super U, ? extends R> resultSelector) {
4760 return flatMap(OperatorMapPair.convertSelector(collectionSelector), resultSelector);
4761 }
4762
4763 /**
4764 * Subscribes to the {@link Observable} and receives notifications for each element.
4765 * <p>
4766 * Alias to {@link #subscribe(Action1)}
4767 * <dl>
4768 * <dt><b>Scheduler:</b></dt>
4769 * <dd>{@code forEach} does not operate by default on a particular {@link Scheduler}.</dd>
4770 * </dl>
4771 *
4772 * @param onNext
4773 * {@link Action1} to execute for each item.
4774 * @throws IllegalArgumentException
4775 * if {@code onNext} is null, or
4776 * if {@code onError} is null, or
4777 * if {@code onComplete} is null
4778 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
4779 */
4780 public final void forEach(final Action1<? super T> onNext) {
4781 subscribe(onNext);
4782 }
4783
4784 /**
4785 * Subscribes to the {@link Observable} and receives notifications for each element and error events.
4786 * <p>
4787 * Alias to {@link #subscribe(Action1, Action1)}
4788 * <dl>
4789 * <dt><b>Scheduler:</b></dt>
4790 * <dd>{@code forEach} does not operate by default on a particular {@link Scheduler}.</dd>
4791 * </dl>
4792 *
4793 * @param onNext
4794 * {@link Action1} to execute for each item.
4795 * @param onError
4796 * {@link Action1} to execute when an error is emitted.
4797 * @throws IllegalArgumentException
4798 * if {@code onNext} is null, or
4799 * if {@code onError} is null, or
4800 * if {@code onComplete} is null
4801 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
4802 */
4803 public final void forEach(final Action1<? super T> onNext, final Action1<Throwable> onError) {
4804 subscribe(onNext, onError);
4805 }
4806
4807 /**
4808 * Subscribes to the {@link Observable} and receives notifications for each element and the terminal events.
4809 * <p>
4810 * Alias to {@link #subscribe(Action1, Action1, Action0)}
4811 * <dl>
4812 * <dt><b>Scheduler:</b></dt>
4813 * <dd>{@code forEach} does not operate by default on a particular {@link Scheduler}.</dd>
4814 * </dl>
4815 *
4816 * @param onNext
4817 * {@link Action1} to execute for each item.
4818 * @param onError
4819 * {@link Action1} to execute when an error is emitted.
4820 * @param onComplete
4821 * {@link Action0} to execute when completion is signalled.
4822 * @throws IllegalArgumentException
4823 * if {@code onNext} is null, or
4824 * if {@code onError} is null, or
4825 * if {@code onComplete} is null
4826 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
4827 */
4828 public final void forEach(final Action1<? super T> onNext, final Action1<Throwable> onError, final Action0 onComplete) {
4829 subscribe(onNext, onError, onComplete);
4830 }
4831
4832 /**
4833 * Groups the items emitted by an {@code Observable} according to a specified criterion, and emits these
4834 * grouped items as {@link GroupedObservable}s, one {@code GroupedObservable} per group.
4835 * <p>
4836 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.png" alt="">
4837 * <p>
4838 * <em>Note:</em> A {@link GroupedObservable} will cache the items it is to emit until such time as it
4839 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
4840 * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
4841 * discard their buffers by applying an operator like {@link #take}{@code (0)} to them.
4842 * <dl>
4843 * <dt><b>Scheduler:</b></dt>
4844 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
4845 * </dl>
4846 *
4847 * @param keySelector
4848 * a function that extracts the key for each item
4849 * @param elementSelector
4850 * a function that extracts the return element for each item
4851 * @param <K>
4852 * the key type
4853 * @param <R>
4854 * the element type
4855 * @return an {@code Observable} that emits {@link GroupedObservable}s, each of which corresponds to a
4856 * unique key value and each of which emits those items from the source Observable that share that
4857 * key value
4858 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
4859 */
4860 public final <K, R> Observable<GroupedObservable<K, R>> groupBy(final Func1<? super T, ? extends K> keySelector, final Func1<? super T, ? extends R> elementSelector) {
4861 return lift(new OperatorGroupBy<T, K, R>(keySelector, elementSelector));
4862 }
4863
4864 /**
4865 * Groups the items emitted by an {@code Observable} according to a specified criterion, and emits these
4866 * grouped items as {@link GroupedObservable}s, one {@code GroupedObservable} per group.
4867 * <p>
4868 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.png" alt="">
4869 * <p>
4870 * <em>Note:</em> A {@link GroupedObservable} will cache the items it is to emit until such time as it
4871 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
4872 * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
4873 * discard their buffers by applying an operator like {@link #take}{@code (0)} to them.
4874 * <dl>
4875 * <dt><b>Scheduler:</b></dt>
4876 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
4877 * </dl>
4878 *
4879 * @param keySelector
4880 * a function that extracts the key for each item
4881 * @param <K>
4882 * the key type
4883 * @return an {@code Observable} that emits {@link GroupedObservable}s, each of which corresponds to a
4884 * unique key value and each of which emits those items from the source Observable that share that
4885 * key value
4886 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
4887 */
4888 public final <K> Observable<GroupedObservable<K, T>> groupBy(final Func1<? super T, ? extends K> keySelector) {
4889 return lift(new OperatorGroupBy<T, K, T>(keySelector));
4890 }
4891
4892 /**
4893 * Returns an Observable that correlates two Observables when they overlap in time and groups the results.
4894 * <p>
4895 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupJoin.png" alt="">
4896 * <dl>
4897 * <dt><b>Scheduler:</b></dt>
4898 * <dd>{@code groupJoin} does not operate by default on a particular {@link Scheduler}.</dd>
4899 * </dl>
4900 *
4901 * @param right
4902 * the other Observable to correlate items from the source Observable with
4903 * @param leftDuration
4904 * a function that returns an Observable whose emissions indicate the duration of the values of
4905 * the source Observable
4906 * @param rightDuration
4907 * a function that returns an Observable whose emissions indicate the duration of the values of
4908 * the {@code right} Observable
4909 * @param resultSelector
4910 * a function that takes an item emitted by each Observable and returns the value to be emitted
4911 * by the resulting Observable
4912 * @return an Observable that emits items based on combining those items emitted by the source Observables
4913 * whose durations overlap
4914 * @see <a href="http://reactivex.io/documentation/operators/join.html">ReactiveX operators documentation: Join</a>
4915 */
4916 public final <T2, D1, D2, R> Observable<R> groupJoin(Observable<T2> right, Func1<? super T, ? extends Observable<D1>> leftDuration,
4917 Func1<? super T2, ? extends Observable<D2>> rightDuration,
4918 Func2<? super T, ? super Observable<T2>, ? extends R> resultSelector) {
4919 return create(new OnSubscribeGroupJoin<T, T2, D1, D2, R>(this, right, leftDuration, rightDuration, resultSelector));
4920 }
4921
4922 /**
4923 * Ignores all items emitted by the source Observable and only calls {@code onCompleted} or {@code onError}.
4924 * <p>
4925 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/ignoreElements.png" alt="">
4926 * <dl>
4927 * <dt><b>Scheduler:</b></dt>
4928 * <dd>{@code ignoreElements} does not operate by default on a particular {@link Scheduler}.</dd>
4929 * </dl>
4930 *
4931 * @return an empty Observable that only calls {@code onCompleted} or {@code onError}, based on which one is
4932 * called by the source Observable
4933 * @see <a href="http://reactivex.io/documentation/operators/ignoreelements.html">ReactiveX operators documentation: IgnoreElements</a>
4934 */
4935 public final Observable<T> ignoreElements() {
4936 return filter(UtilityFunctions.alwaysFalse());
4937 }
4938
4939 /**
4940 * Returns an Observable that emits {@code true} if the source Observable is empty, otherwise {@code false}.
4941 * <p>
4942 * In Rx.Net this is negated as the {@code any} Observer but we renamed this in RxJava to better match Java
4943 * naming idioms.
4944 * <p>
4945 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/isEmpty.png" alt="">
4946 * <dl>
4947 * <dt><b>Scheduler:</b></dt>
4948 * <dd>{@code isEmpty} does not operate by default on a particular {@link Scheduler}.</dd>
4949 * </dl>
4950 *
4951 * @return an Observable that emits a Boolean
4952 * @see <a href="http://reactivex.io/documentation/operators/contains.html">ReactiveX operators documentation: Contains</a>
4953 */
4954 public final Observable<Boolean> isEmpty() {
4955 return lift(new OperatorAny<T>(UtilityFunctions.alwaysTrue(), true));
4956 }
4957
4958 /**
4959 * Correlates the items emitted by two Observables based on overlapping durations.
4960 * <p>
4961 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/join_.png" alt="">
4962 * <dl>
4963 * <dt><b>Scheduler:</b></dt>
4964 * <dd>{@code join} does not operate by default on a particular {@link Scheduler}.</dd>
4965 * </dl>
4966 *
4967 * @param right
4968 * the second Observable to join items from
4969 * @param leftDurationSelector
4970 * a function to select a duration for each item emitted by the source Observable, used to
4971 * determine overlap
4972 * @param rightDurationSelector
4973 * a function to select a duration for each item emitted by the {@code right} Observable, used to
4974 * determine overlap
4975 * @param resultSelector
4976 * a function that computes an item to be emitted by the resulting Observable for any two
4977 * overlapping items emitted by the two Observables
4978 * @return an Observable that emits items correlating to items emitted by the source Observables that have
4979 * overlapping durations
4980 * @see <a href="http://reactivex.io/documentation/operators/join.html">ReactiveX operators documentation: Join</a>
4981 */
4982 public final <TRight, TLeftDuration, TRightDuration, R> Observable<R> join(Observable<TRight> right, Func1<T, Observable<TLeftDuration>> leftDurationSelector,
4983 Func1<TRight, Observable<TRightDuration>> rightDurationSelector,
4984 Func2<T, TRight, R> resultSelector) {
4985 return create(new OnSubscribeJoin<T, TRight, TLeftDuration, TRightDuration, R>(this, right, leftDurationSelector, rightDurationSelector, resultSelector));
4986 }
4987
4988 /**
4989 * Returns an Observable that emits the last item emitted by the source Observable or notifies observers of
4990 * a {@code NoSuchElementException} if the source Observable is empty.
4991 * <p>
4992 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/last.png" alt="">
4993 * <dl>
4994 * <dt><b>Scheduler:</b></dt>
4995 * <dd>{@code last} does not operate by default on a particular {@link Scheduler}.</dd>
4996 * </dl>
4997 *
4998 * @return an Observable that emits the last item from the source Observable or notifies observers of an
4999 * error
5000 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
5001 */
5002 public final Observable<T> last() {
5003 return takeLast(1).single();
5004 }
5005
5006 /**
5007 * Returns an Observable that emits only the last item emitted by the source Observable that satisfies a
5008 * given condition, or notifies of a {@code NoSuchElementException} if no such items are emitted.
5009 * <p>
5010 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/last.p.png" alt="">
5011 * <dl>
5012 * <dt><b>Scheduler:</b></dt>
5013 * <dd>{@code last} does not operate by default on a particular {@link Scheduler}.</dd>
5014 * </dl>
5015 *
5016 * @param predicate
5017 * the condition any source emitted item has to satisfy
5018 * @return an Observable that emits only the last item satisfying the given condition from the source, or an
5019 * {@code NoSuchElementException} if no such items are emitted
5020 * @throws IllegalArgumentException
5021 * if no items that match the predicate are emitted by the source Observable
5022 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
5023 */
5024 public final Observable<T> last(Func1<? super T, Boolean> predicate) {
5025 return filter(predicate).takeLast(1).single();
5026 }
5027
5028 /**
5029 * Returns an Observable that emits only the last item emitted by the source Observable, or a default item
5030 * if the source Observable completes without emitting any items.
5031 * <p>
5032 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrDefault.png" alt="">
5033 * <dl>
5034 * <dt><b>Scheduler:</b></dt>
5035 * <dd>{@code lastOrDefault} does not operate by default on a particular {@link Scheduler}.</dd>
5036 * </dl>
5037 *
5038 * @param defaultValue
5039 * the default item to emit if the source Observable is empty
5040 * @return an Observable that emits only the last item emitted by the source Observable, or a default item
5041 * if the source Observable is empty
5042 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
5043 */
5044 public final Observable<T> lastOrDefault(T defaultValue) {
5045 return takeLast(1).singleOrDefault(defaultValue);
5046 }
5047
5048 /**
5049 * Returns an Observable that emits only the last item emitted by the source Observable that satisfies a
5050 * specified condition, or a default item if no such item is emitted by the source Observable.
5051 * <p>
5052 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrDefault.p.png" alt="">
5053 * <dl>
5054 * <dt><b>Scheduler:</b></dt>
5055 * <dd>{@code lastOrDefault} does not operate by default on a particular {@link Scheduler}.</dd>
5056 * </dl>
5057 *
5058 * @param defaultValue
5059 * the default item to emit if the source Observable doesn't emit anything that satisfies the
5060 * specified {@code predicate}
5061 * @param predicate
5062 * the condition any item emitted by the source Observable has to satisfy
5063 * @return an Observable that emits only the last item emitted by the source Observable that satisfies the
5064 * given condition, or a default item if no such item is emitted by the source Observable
5065 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
5066 */
5067 public final Observable<T> lastOrDefault(T defaultValue, Func1<? super T, Boolean> predicate) {
5068 return filter(predicate).takeLast(1).singleOrDefault(defaultValue);
5069 }
5070
5071 /**
5072 * Returns an Observable that emits only the first {@code num} items emitted by the source Observable.
5073 * <p>
5074 * Alias of {@link #take(int)} to match Java 8 Stream API naming convention.
5075 * <p>
5076 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.png" alt="">
5077 * <p>
5078 * This method returns an Observable that will invoke a subscribing {@link Observer}'s
5079 * {@link Observer#onNext onNext} function a maximum of {@code num} times before invoking
5080 * {@link Observer#onCompleted onCompleted}.
5081 * <dl>
5082 * <dt><b>Scheduler:</b></dt>
5083 * <dd>{@code limit} does not operate by default on a particular {@link Scheduler}.</dd>
5084 * </dl>
5085 *
5086 * @param num
5087 * the maximum number of items to emit
5088 * @return an Observable that emits only the first {@code num} items emitted by the source Observable, or
5089 * all of the items from the source Observable if that Observable emits fewer than {@code num} items
5090 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
5091 */
5092 public final Observable<T> limit(int num) {
5093 return take(num);
5094 }
5095
5096 /**
5097 * Returns an Observable that applies a specified function to each item emitted by the source Observable and
5098 * emits the results of these function applications.
5099 * <p>
5100 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/map.png" alt="">
5101 * <dl>
5102 * <dt><b>Scheduler:</b></dt>
5103 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
5104 * </dl>
5105 *
5106 * @param func
5107 * a function to apply to each item emitted by the Observable
5108 * @return an Observable that emits the items from the source Observable, transformed by the specified
5109 * function
5110 * @see <a href="http://reactivex.io/documentation/operators/map.html">ReactiveX operators documentation: Map</a>
5111 */
5112 public final <R> Observable<R> map(Func1<? super T, ? extends R> func) {
5113 return lift(new OperatorMap<T, R>(func));
5114 }
5115
5116 private final <R> Observable<R> mapNotification(Func1<? super T, ? extends R> onNext, Func1<? super Throwable, ? extends R> onError, Func0<? extends R> onCompleted) {
5117 return lift(new OperatorMapNotification<T, R>(onNext, onError, onCompleted));
5118 }
5119
5120 /**
5121 * Returns an Observable that represents all of the emissions <em>and</em> notifications from the source
5122 * Observable into emissions marked with their original types within {@link Notification} objects.
5123 * <p>
5124 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/materialize.png" alt="">
5125 * <dl>
5126 * <dt><b>Scheduler:</b></dt>
5127 * <dd>{@code materialize} does not operate by default on a particular {@link Scheduler}.</dd>
5128 * </dl>
5129 *
5130 * @return an Observable that emits items that are the result of materializing the items and notifications
5131 * of the source Observable
5132 * @see <a href="http://reactivex.io/documentation/operators/materialize-dematerialize.html">ReactiveX operators documentation: Materialize</a>
5133 */
5134 public final Observable<Notification<T>> materialize() {
5135 return lift(OperatorMaterialize.<T>instance());
5136 }
5137
5138 /**
5139 * Flattens this and another Observable into a single Observable, without any transformation.
5140 * <p>
5141 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.png" alt="">
5142 * <p>
5143 * You can combine items emitted by multiple Observables so that they appear as a single Observable, by
5144 * using the {@code mergeWith} method.
5145 * <dl>
5146 * <dt><b>Scheduler:</b></dt>
5147 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
5148 * </dl>
5149 *
5150 * @param t1
5151 * an Observable to be merged
5152 * @return an Observable that emits all of the items emitted by the source Observables
5153 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
5154 */
5155 public final Observable<T> mergeWith(Observable<? extends T> t1) {
5156 return merge(this, t1);
5157 }
5158
5159 /**
5160 * Modifies an Observable to perform its emissions and notifications on a specified {@link Scheduler},
5161 * asynchronously with an unbounded buffer.
5162 * <p>
5163 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/observeOn.png" alt="">
5164 * <dl>
5165 * <dt><b>Scheduler:</b></dt>
5166 * <dd>you specify which {@link Scheduler} this operator will use</dd>
5167 * </dl>
5168 *
5169 * @param scheduler
5170 * the {@link Scheduler} to notify {@link Observer}s on
5171 * @return the source Observable modified so that its {@link Observer}s are notified on the specified
5172 * {@link Scheduler}
5173 * @see <a href="http://reactivex.io/documentation/operators/observeon.html">ReactiveX operators documentation: ObserveOn</a>
5174 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
5175 * @see #subscribeOn
5176 */
5177 public final Observable<T> observeOn(Scheduler scheduler) {
5178 if (this instanceof ScalarSynchronousObservable) {
5179 return ((ScalarSynchronousObservable<T>)this).scalarScheduleOn(scheduler);
5180 }
5181 return lift(new OperatorObserveOn<T>(scheduler));
5182 }
5183
5184 /**
5185 * Filters the items emitted by an Observable, only emitting those of the specified type.
5186 * <p>
5187 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/ofClass.png" alt="">
5188 * <dl>
5189 * <dt><b>Scheduler:</b></dt>
5190 * <dd>{@code ofType} does not operate by default on a particular {@link Scheduler}.</dd>
5191 * </dl>
5192 *
5193 * @param klass
5194 * the class type to filter the items emitted by the source Observable
5195 * @return an Observable that emits items from the source Observable of type {@code klass}
5196 * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
5197 */
5198 public final <R> Observable<R> ofType(final Class<R> klass) {
5199 return filter(new Func1<T, Boolean>() {
5200 @Override
5201 public final Boolean call(T t) {
5202 return klass.isInstance(t);
5203 }
5204 }).cast(klass);
5205 }
5206
5207 /**
5208 * Instructs an Observable that is emitting items faster than its observer can consume them to buffer these
5209 * items indefinitely until they can be emitted.
5210 * <p>
5211 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.png" alt="">
5212 * <dl>
5213 * <dt><b>Scheduler:</b></dt>
5214 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
5215 * </dl>
5216 *
5217 * @return the source Observable modified to buffer items to the extent system resources allow
5218 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
5219 */
5220 public final Observable<T> onBackpressureBuffer() {
5221 return lift(new OperatorOnBackpressureBuffer<T>());
5222 }
5223
5224 /**
5225 * Instructs an Observable that is emitting items faster than its observer can consume them to buffer up to
5226 * a given amount of items until they can be emitted. The resulting Observable will {@code onError} emitting
5227 * a {@code BufferOverflowException} as soon as the buffer's capacity is exceeded, dropping all undelivered
5228 * items, and unsubscribing from the source.
5229 * <p>
5230 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.png" alt="">
5231 * <dl>
5232 * <dt><b>Scheduler:</b></dt>
5233 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
5234 * </dl>
5235 *
5236 * @return the source Observable modified to buffer items up to the given capacity
5237 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
5238 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
5239 */
5240 @Beta
5241 public final Observable<T> onBackpressureBuffer(long capacity) {
5242 return lift(new OperatorOnBackpressureBuffer<T>(capacity));
5243 }
5244
5245 /**
5246 * Instructs an Observable that is emitting items faster than its observer can consume them to buffer up to
5247 * a given amount of items until they can be emitted. The resulting Observable will {@code onError} emitting
5248 * a {@code BufferOverflowException} as soon as the buffer's capacity is exceeded, dropping all undelivered
5249 * items, unsubscribing from the source, and notifying the producer with {@code onOverflow}.
5250 * <p>
5251 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.png" alt="">
5252 * <dl>
5253 * <dt><b>Scheduler:</b></dt>
5254 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
5255 * </dl>
5256 *
5257 * @return the source Observable modified to buffer items up to the given capacity
5258 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
5259 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
5260 */
5261 @Beta
5262 public final Observable<T> onBackpressureBuffer(long capacity, Action0 onOverflow) {
5263 return lift(new OperatorOnBackpressureBuffer<T>(capacity, onOverflow));
5264 }
5265
5266 /**
5267 * Instructs an Observable that is emitting items faster than its observer can consume them to discard,
5268 * rather than emit, those items that its observer is not prepared to observe.
5269 * <p>
5270 * <img width="640" height="245" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.drop.png" alt="">
5271 * <p>
5272 * If the downstream request count hits 0 then the Observable will refrain from calling {@code onNext} until
5273 * the observer invokes {@code request(n)} again to increase the request count.
5274 * <dl>
5275 * <dt><b>Scheduler:</b></dt>
5276 * <dd>{@code onBackpressureDrop} does not operate by default on a particular {@link Scheduler}.</dd>
5277 * </dl>
5278 *
5279 * @param onDrop the action to invoke for each item dropped. onDrop action should be fast and should never block.
5280 * @return the source Observable modified to drop {@code onNext} notifications on overflow
5281 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
5282 * @Experimental The behavior of this can change at any time.
5283 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
5284 */
5285 @Experimental
5286 public final Observable<T> onBackpressureDrop(Action1<? super T> onDrop) {
5287 return lift(new OperatorOnBackpressureDrop<T>(onDrop));
5288 }
5289
5290 /**
5291 * Instructs an Observable that is emitting items faster than its observer can consume them to discard,
5292 * rather than emit, those items that its observer is not prepared to observe.
5293 * <p>
5294 * <img width="640" height="245" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.drop.png" alt="">
5295 * <p>
5296 * If the downstream request count hits 0 then the Observable will refrain from calling {@code onNext} until
5297 * the observer invokes {@code request(n)} again to increase the request count.
5298 * <dl>
5299 * <dt><b>Scheduler:</b></dt>
5300 * <dd>{@code onBackpressureDrop} does not operate by default on a particular {@link Scheduler}.</dd>
5301 * </dl>
5302 *
5303 * @return the source Observable modified to drop {@code onNext} notifications on overflow
5304 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
5305 */
5306 public final Observable<T> onBackpressureDrop() {
5307 return lift(OperatorOnBackpressureDrop.<T>instance());
5308 }
5309
5310 /**
5311 * Instructs an Observable that is emitting items faster than its observer can consume them to
5312 * block the producer thread.
5313 * <p>
5314 * <img width="640" height="245" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.block.png" alt="">
5315 * <p>
5316 * The producer side can emit up to {@code maxQueueLength} onNext elements without blocking, but the
5317 * consumer side considers the amount its downstream requested through {@code Producer.request(n)}
5318 * and doesn't emit more than requested even if more is available. For example, using
5319 * {@code onBackpressureBlock(384).observeOn(Schedulers.io())} will not throw a MissingBackpressureException.
5320 * <p>
5321 * Note that if the upstream Observable does support backpressure, this operator ignores that capability
5322 * and doesn't propagate any backpressure requests from downstream.
5323 *
5324 * @param maxQueueLength the maximum number of items the producer can emit without blocking
5325 * @return the source Observable modified to block {@code onNext} notifications on overflow
5326 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
5327 * @Experimental The behavior of this can change at any time.
5328 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
5329 */
5330 @Experimental
5331 public final Observable<T> onBackpressureBlock(int maxQueueLength) {
5332 return lift(new OperatorOnBackpressureBlock<T>(maxQueueLength));
5333 }
5334 /**
5335 * Instructs an Observable that is emitting items faster than its observer can consume them to block the
5336 * producer thread if the number of undelivered onNext events reaches the system-wide ring buffer size.
5337 * <p>
5338 * <img width="640" height="245" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.block.png" alt="">
5339 * <p>
5340 * The producer side can emit up to the system-wide ring buffer size onNext elements without blocking, but
5341 * the consumer side considers the amount its downstream requested through {@code Producer.request(n)}
5342 * and doesn't emit more than requested even if available.
5343 * <p>
5344 * Note that if the upstream Observable does support backpressure, this operator ignores that capability
5345 * and doesn't propagate any backpressure requests from downstream.
5346 *
5347 * @return the source Observable modified to block {@code onNext} notifications on overflow
5348 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
5349 * @Experimental The behavior of this can change at any time.
5350 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
5351 */
5352 @Experimental
5353 public final Observable<T> onBackpressureBlock() {
5354 return onBackpressureBlock(rx.internal.util.RxRingBuffer.SIZE);
5355 }
5356
5357 /**
5358 * Instructs an Observable to pass control to another Observable rather than invoking
5359 * {@link Observer#onError onError} if it encounters an error.
5360 * <p>
5361 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorResumeNext.png" alt="">
5362 * <p>
5363 * By default, when an Observable encounters an error that prevents it from emitting the expected item to
5364 * its {@link Observer}, the Observable invokes its Observer's {@code onError} method, and then quits
5365 * without invoking any more of its Observer's methods. The {@code onErrorResumeNext} method changes this
5366 * behavior. If you pass a function that returns an Observable ({@code resumeFunction}) to
5367 * {@code onErrorResumeNext}, if the original Observable encounters an error, instead of invoking its
5368 * Observer's {@code onError} method, it will instead relinquish control to the Observable returned from
5369 * {@code resumeFunction}, which will invoke the Observer's {@link Observer#onNext onNext} method if it is
5370 * able to do so. In such a case, because no Observable necessarily invokes {@code onError}, the Observer
5371 * may never know that an error happened.
5372 * <p>
5373 * You can use this to prevent errors from propagating or to supply fallback data should errors be
5374 * encountered.
5375 * <dl>
5376 * <dt><b>Scheduler:</b></dt>
5377 * <dd>{@code onErrorResumeNext} does not operate by default on a particular {@link Scheduler}.</dd>
5378 * </dl>
5379 *
5380 * @param resumeFunction
5381 * a function that returns an Observable that will take over if the source Observable encounters
5382 * an error
5383 * @return the original Observable, with appropriately modified behavior
5384 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
5385 */
5386 public final Observable<T> onErrorResumeNext(final Func1<Throwable, ? extends Observable<? extends T>> resumeFunction) {
5387 return lift(new OperatorOnErrorResumeNextViaFunction<T>(resumeFunction));
5388 }
5389
5390 /**
5391 * Instructs an Observable to pass control to another Observable rather than invoking
5392 * {@link Observer#onError onError} if it encounters an error.
5393 * <p>
5394 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorResumeNext.png" alt="">
5395 * <p>
5396 * By default, when an Observable encounters an error that prevents it from emitting the expected item to
5397 * its {@link Observer}, the Observable invokes its Observer's {@code onError} method, and then quits
5398 * without invoking any more of its Observer's methods. The {@code onErrorResumeNext} method changes this
5399 * behavior. If you pass another Observable ({@code resumeSequence}) to an Observable's
5400 * {@code onErrorResumeNext} method, if the original Observable encounters an error, instead of invoking its
5401 * Observer's {@code onError} method, it will instead relinquish control to {@code resumeSequence} which
5402 * will invoke the Observer's {@link Observer#onNext onNext} method if it is able to do so. In such a case,
5403 * because no Observable necessarily invokes {@code onError}, the Observer may never know that an error
5404 * happened.
5405 * <p>
5406 * You can use this to prevent errors from propagating or to supply fallback data should errors be
5407 * encountered.
5408 * <dl>
5409 * <dt><b>Scheduler:</b></dt>
5410 * <dd>{@code onErrorResumeNext} does not operate by default on a particular {@link Scheduler}.</dd>
5411 * </dl>
5412 *
5413 * @param resumeSequence
5414 * a function that returns an Observable that will take over if the source Observable encounters
5415 * an error
5416 * @return the original Observable, with appropriately modified behavior
5417 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
5418 */
5419 public final Observable<T> onErrorResumeNext(final Observable<? extends T> resumeSequence) {
5420 return lift(new OperatorOnErrorResumeNextViaObservable<T>(resumeSequence));
5421 }
5422
5423 /**
5424 * Instructs an Observable to emit an item (returned by a specified function) rather than invoking
5425 * {@link Observer#onError onError} if it encounters an error.
5426 * <p>
5427 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorReturn.png" alt="">
5428 * <p>
5429 * By default, when an Observable encounters an error that prevents it from emitting the expected item to
5430 * its {@link Observer}, the Observable invokes its Observer's {@code onError} method, and then quits
5431 * without invoking any more of its Observer's methods. The {@code onErrorReturn} method changes this
5432 * behavior. If you pass a function ({@code resumeFunction}) to an Observable's {@code onErrorReturn}
5433 * method, if the original Observable encounters an error, instead of invoking its Observer's
5434 * {@code onError} method, it will instead emit the return value of {@code resumeFunction}.
5435 * <p>
5436 * You can use this to prevent errors from propagating or to supply fallback data should errors be
5437 * encountered.
5438 * <dl>
5439 * <dt><b>Scheduler:</b></dt>
5440 * <dd>{@code onErrorReturn} does not operate by default on a particular {@link Scheduler}.</dd>
5441 * </dl>
5442 *
5443 * @param resumeFunction
5444 * a function that returns an item that the new Observable will emit if the source Observable
5445 * encounters an error
5446 * @return the original Observable with appropriately modified behavior
5447 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
5448 */
5449 public final Observable<T> onErrorReturn(Func1<Throwable, ? extends T> resumeFunction) {
5450 return lift(new OperatorOnErrorReturn<T>(resumeFunction));
5451 }
5452
5453 /**
5454 * Instructs an Observable to pass control to another Observable rather than invoking
5455 * {@link Observer#onError onError} if it encounters an {@link java.lang.Exception}.
5456 * <p>
5457 * This differs from {@link #onErrorResumeNext} in that this one does not handle {@link java.lang.Throwable}
5458 * or {@link java.lang.Error} but lets those continue through.
5459 * <p>
5460 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onExceptionResumeNextViaObservable.png" alt="">
5461 * <p>
5462 * By default, when an Observable encounters an exception that prevents it from emitting the expected item
5463 * to its {@link Observer}, the Observable invokes its Observer's {@code onError} method, and then quits
5464 * without invoking any more of its Observer's methods. The {@code onExceptionResumeNext} method changes
5465 * this behavior. If you pass another Observable ({@code resumeSequence}) to an Observable's
5466 * {@code onExceptionResumeNext} method, if the original Observable encounters an exception, instead of
5467 * invoking its Observer's {@code onError} method, it will instead relinquish control to
5468 * {@code resumeSequence} which will invoke the Observer's {@link Observer#onNext onNext} method if it is
5469 * able to do so. In such a case, because no Observable necessarily invokes {@code onError}, the Observer
5470 * may never know that an exception happened.
5471 * <p>
5472 * You can use this to prevent exceptions from propagating or to supply fallback data should exceptions be
5473 * encountered.
5474 * <dl>
5475 * <dt><b>Scheduler:</b></dt>
5476 * <dd>{@code onErrorResumeNext} does not operate by default on a particular {@link Scheduler}.</dd>
5477 * </dl>
5478 *
5479 * @param resumeSequence
5480 * a function that returns an Observable that will take over if the source Observable encounters
5481 * an exception
5482 * @return the original Observable, with appropriately modified behavior
5483 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
5484 */
5485 public final Observable<T> onExceptionResumeNext(final Observable<? extends T> resumeSequence) {
5486 return lift(new OperatorOnExceptionResumeNextViaObservable<T>(resumeSequence));
5487 }
5488
5489 /**
5490 * Returns a {@link ConnectableObservable}, which is a variety of Observable that waits until its
5491 * {@link ConnectableObservable#connect connect} method is called before it begins emitting items to those
5492 * {@link Observer}s that have subscribed to it.
5493 * <p>
5494 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishConnect.png" alt="">
5495 * <dl>
5496 * <dt><b>Scheduler:</b></dt>
5497 * <dd>{@code publish} does not operate by default on a particular {@link Scheduler}.</dd>
5498 * </dl>
5499 *
5500 * @return a {@link ConnectableObservable} that upon connection causes the source Observable to emit items
5501 * to its {@link Observer}s
5502 * @see <a href="http://reactivex.io/documentation/operators/publish.html">ReactiveX operators documentation: Publish</a>
5503 */
5504 public final ConnectableObservable<T> publish() {
5505 return OperatorPublish.create(this);
5506 }
5507
5508 /**
5509 * Returns an Observable that emits the results of invoking a specified selector on items emitted by a
5510 * {@link ConnectableObservable} that shares a single subscription to the underlying sequence.
5511 * <p>
5512 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishConnect.f.png" alt="">
5513 * <dl>
5514 * <dt><b>Scheduler:</b></dt>
5515 * <dd>{@code publish} does not operate by default on a particular {@link Scheduler}.</dd>
5516 * </dl>
5517 *
5518 * @param <R>
5519 * the type of items emitted by the resulting Observable
5520 * @param selector
5521 * a function that can use the multicasted source sequence as many times as needed, without
5522 * causing multiple subscriptions to the source sequence. Subscribers to the given source will
5523 * receive all notifications of the source from the time of the subscription forward.
5524 * @return an Observable that emits the results of invoking the selector on the items emitted by a {@link ConnectableObservable} that shares a single subscription to the underlying sequence
5525 * @see <a href="http://reactivex.io/documentation/operators/publish.html">ReactiveX operators documentation: Publish</a>
5526 */
5527 public final <R> Observable<R> publish(Func1<? super Observable<T>, ? extends Observable<R>> selector) {
5528 return OperatorPublish.create(this, selector);
5529 }
5530
5531 /**
5532 * Returns an Observable that applies a specified accumulator function to the first item emitted by a source
5533 * Observable, then feeds the result of that function along with the second item emitted by the source
5534 * Observable into the same function, and so on until all items have been emitted by the source Observable,
5535 * and emits the final result from the final call to your function as its sole item.
5536 * <p>
5537 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/reduce.png" alt="">
5538 * <p>
5539 * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate,"
5540 * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method
5541 * that does a similar operation on lists.
5542 * <dl>
5543 * <dt><b>Backpressure Support:</b></dt>
5544 * <dd>This operator does not support backpressure because by intent it will receive all values and reduce
5545 * them to a single {@code onNext}.</dd>
5546 * <dt><b>Scheduler:</b></dt>
5547 * <dd>{@code reduce} does not operate by default on a particular {@link Scheduler}.</dd>
5548 * </dl>
5549 *
5550 * @param accumulator
5551 * an accumulator function to be invoked on each item emitted by the source Observable, whose
5552 * result will be used in the next accumulator call
5553 * @return an Observable that emits a single item that is the result of accumulating the items emitted by
5554 * the source Observable
5555 * @throws IllegalArgumentException
5556 * if the source Observable emits no items
5557 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
5558 * @see <a href="http://en.wikipedia.org/wiki/Fold_(higher-order_function)">Wikipedia: Fold (higher-order function)</a>
5559 */
5560 public final Observable<T> reduce(Func2<T, T, T> accumulator) {
5561 /*
5562 * Discussion and confirmation of implementation at
5563 * https://github.com/ReactiveX/RxJava/issues/423#issuecomment-27642532
5564 *
5565 * It should use last() not takeLast(1) since it needs to emit an error if the sequence is empty.
5566 */
5567 return scan(accumulator).last();
5568 }
5569
5570 /**
5571 * Returns an Observable that applies a specified accumulator function to the first item emitted by a source
5572 * Observable and a specified seed value, then feeds the result of that function along with the second item
5573 * emitted by an Observable into the same function, and so on until all items have been emitted by the
5574 * source Observable, emitting the final result from the final call to your function as its sole item.
5575 * <p>
5576 * <img width="640" height="325" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/reduceSeed.png" alt="">
5577 * <p>
5578 * This technique, which is called "reduce" here, is sometimec called "aggregate," "fold," "accumulate,"
5579 * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method
5580 * that does a similar operation on lists.
5581 * <dl>
5582 * <dt><b>Backpressure Support:</b></dt>
5583 * <dd>This operator does not support backpressure because by intent it will receive all values and reduce
5584 * them to a single {@code onNext}.</dd>
5585 * <dt><b>Scheduler:</b></dt>
5586 * <dd>{@code reduce} does not operate by default on a particular {@link Scheduler}.</dd>
5587 * </dl>
5588 *
5589 * @param initialValue
5590 * the initial (seed) accumulator value
5591 * @param accumulator
5592 * an accumulator function to be invoked on each item emitted by the source Observable, the
5593 * result of which will be used in the next accumulator call
5594 * @return an Observable that emits a single item that is the result of accumulating the output from the
5595 * items emitted by the source Observable
5596 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
5597 * @see <a href="http://en.wikipedia.org/wiki/Fold_(higher-order_function)">Wikipedia: Fold (higher-order function)</a>
5598 */
5599 public final <R> Observable<R> reduce(R initialValue, Func2<R, ? super T, R> accumulator) {
5600 return scan(initialValue, accumulator).takeLast(1);
5601 }
5602
5603 /**
5604 * Returns an Observable that repeats the sequence of items emitted by the source Observable indefinitely.
5605 * <p>
5606 * <img width="640" height="309" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeat.o.png" alt="">
5607 * <dl>
5608 * <dt><b>Scheduler:</b></dt>
5609 * <dd>{@code repeat} operates by default on the {@code trampoline} {@link Scheduler}.</dd>
5610 * </dl>
5611 *
5612 * @return an Observable that emits the items emitted by the source Observable repeatedly and in sequence
5613 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
5614 */
5615 public final Observable<T> repeat() {
5616 return OnSubscribeRedo.<T>repeat(this);
5617 }
5618
5619 /**
5620 * Returns an Observable that repeats the sequence of items emitted by the source Observable indefinitely,
5621 * on a particular Scheduler.
5622 * <p>
5623 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeat.os.png" alt="">
5624 * <dl>
5625 * <dt><b>Scheduler:</b></dt>
5626 * <dd>you specify which {@link Scheduler} this operator will use</dd>
5627 * </dl>
5628 *
5629 * @param scheduler
5630 * the Scheduler to emit the items on
5631 * @return an Observable that emits the items emitted by the source Observable repeatedly and in sequence
5632 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
5633 */
5634 public final Observable<T> repeat(Scheduler scheduler) {
5635 return OnSubscribeRedo.<T>repeat(this, scheduler);
5636 }
5637
5638 /**
5639 * Returns an Observable that repeats the sequence of items emitted by the source Observable at most
5640 * {@code count} times.
5641 * <p>
5642 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeat.on.png" alt="">
5643 * <dl>
5644 * <dt><b>Scheduler:</b></dt>
5645 * <dd>{@code repeat} operates by default on the {@code trampoline} {@link Scheduler}.</dd>
5646 * </dl>
5647 *
5648 * @param count
5649 * the number of times the source Observable items are repeated, a count of 0 will yield an empty
5650 * sequence
5651 * @return an Observable that repeats the sequence of items emitted by the source Observable at most
5652 * {@code count} times
5653 * @throws IllegalArgumentException
5654 * if {@code count} is less than zero
5655 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
5656 */
5657 public final Observable<T> repeat(final long count) {
5658 return OnSubscribeRedo.<T>repeat(this, count);
5659 }
5660
5661 /**
5662 * Returns an Observable that repeats the sequence of items emitted by the source Observable at most
5663 * {@code count} times, on a particular Scheduler.
5664 * <p>
5665 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeat.ons.png" alt="">
5666 * <dl>
5667 * <dt><b>Scheduler:</b></dt>
5668 * <dd>you specify which {@link Scheduler} this operator will use</dd>
5669 * </dl>
5670 *
5671 * @param count
5672 * the number of times the source Observable items are repeated, a count of 0 will yield an empty
5673 * sequence
5674 * @param scheduler
5675 * the {@link Scheduler} to emit the items on
5676 * @return an Observable that repeats the sequence of items emitted by the source Observable at most
5677 * {@code count} times on a particular Scheduler
5678 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
5679 */
5680 public final Observable<T> repeat(final long count, Scheduler scheduler) {
5681 return OnSubscribeRedo.<T>repeat(this, count, scheduler);
5682 }
5683
5684 /**
5685 * Returns an Observable that emits the same values as the source Observable with the exception of an
5686 * {@code onCompleted}. An {@code onCompleted} notification from the source will result in the emission of
5687 * a {@code void} item to the Observable provided as an argument to the {@code notificationHandler}
5688 * function. If that Observable calls {@code onComplete} or {@code onError} then {@code repeatWhen} will
5689 * call {@code onCompleted} or {@code onError} on the child subscription. Otherwise, this Observable will
5690 * resubscribe to the source Observable, on a particular Scheduler.
5691 * <p>
5692 * <img width="640" height="430" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeatWhen.f.png" alt="">
5693 * <dl>
5694 * <dt><b>Scheduler:</b></dt>
5695 * <dd>you specify which {@link Scheduler} this operator will use</dd>
5696 * </dl>
5697 *
5698 * @param notificationHandler
5699 * receives an Observable of notifications with which a user can complete or error, aborting the repeat.
5700 * @param scheduler
5701 * the {@link Scheduler} to emit the items on
5702 * @return the source Observable modified with repeat logic
5703 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
5704 */
5705 public final Observable<T> repeatWhen(final Func1<? super Observable<? extends Void>, ? extends Observable<?>> notificationHandler, Scheduler scheduler) {
5706 Func1<? super Observable<? extends Notification<?>>, ? extends Observable<?>> dematerializedNotificationHandler = new Func1<Observable<? extends Notification<?>>, Observable<?>>() {
5707 @Override
5708 public Observable<?> call(Observable<? extends Notification<?>> notifications) {
5709 return notificationHandler.call(notifications.map(new Func1<Notification<?>, Void>() {
5710 @Override
5711 public Void call(Notification<?> notification) {
5712 return null;
5713 }
5714 }));
5715 }
5716 };
5717 return OnSubscribeRedo.repeat(this, dematerializedNotificationHandler, scheduler);
5718 }
5719
5720 /**
5721 * Returns an Observable that emits the same values as the source Observable with the exception of an
5722 * {@code onCompleted}. An {@code onCompleted} notification from the source will result in the emission of
5723 * a {@code void} item to the Observable provided as an argument to the {@code notificationHandler}
5724 * function. If that Observable calls {@code onComplete} or {@code onError} then {@code repeatWhen} will
5725 * call {@code onCompleted} or {@code onError} on the child subscription. Otherwise, this Observable will
5726 * resubscribe to the source observable.
5727 * <p>
5728 * <img width="640" height="430" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeatWhen.f.png" alt="">
5729 * <dl>
5730 * <dt><b>Scheduler:</b></dt>
5731 * <dd>{@code repeatWhen} operates by default on the {@code trampoline} {@link Scheduler}.</dd>
5732 * </dl>
5733 *
5734 * @param notificationHandler
5735 * receives an Observable of notifications with which a user can complete or error, aborting the repeat.
5736 * @return the source Observable modified with repeat logic
5737 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
5738 */
5739 public final Observable<T> repeatWhen(final Func1<? super Observable<? extends Void>, ? extends Observable<?>> notificationHandler) {
5740 Func1<? super Observable<? extends Notification<?>>, ? extends Observable<?>> dematerializedNotificationHandler = new Func1<Observable<? extends Notification<?>>, Observable<?>>() {
5741 @Override
5742 public Observable<?> call(Observable<? extends Notification<?>> notifications) {
5743 return notificationHandler.call(notifications.map(new Func1<Notification<?>, Void>() {
5744 @Override
5745 public Void call(Notification<?> notification) {
5746 return null;
5747 }
5748 }));
5749 }
5750 };
5751 return OnSubscribeRedo.repeat(this, dematerializedNotificationHandler);
5752 }
5753
5754 /**
5755 * Returns a {@link ConnectableObservable} that shares a single subscription to the underlying Observable
5756 * that will replay all of its items and notifications to any future {@link Observer}. A Connectable
5757 * Observable resembles an ordinary Observable, except that it does not begin emitting items when it is
5758 * subscribed to, but only when its {@code connect} method is called.
5759 * <p>
5760 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.png" alt="">
5761 * <dl>
5762 * <dt><b>Backpressure Support:</b></dt>
5763 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
5764 * multiple subscribers. Each child will need to manage backpressure independently using operators such
5765 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
5766 * <dt><b>Scheduler:</b></dt>
5767 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
5768 * </dl>
5769 *
5770 * @return a {@link ConnectableObservable} that upon connection causes the source Observable to emit its
5771 * items to its {@link Observer}s
5772 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
5773 */
5774 public final ConnectableObservable<T> replay() {
5775 return new OperatorMulticast<T, T>(this, new Func0<Subject<? super T, ? extends T>>() {
5776
5777 @Override
5778 public Subject<? super T, ? extends T> call() {
5779 return ReplaySubject.<T> create();
5780 }
5781
5782 });
5783 }
5784
5785 /**
5786 * Returns an Observable that emits items that are the results of invoking a specified selector on the items
5787 * emitted by a {@link ConnectableObservable} that shares a single subscription to the source Observable.
5788 * <p>
5789 * <img width="640" height="450" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.f.png" alt="">
5790 * <dl>
5791 * <dt><b>Backpressure Support:</b></dt>
5792 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
5793 * multiple subscribers. Each child will need to manage backpressure independently using operators such
5794 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
5795 * <dt><b>Scheduler:</b></dt>
5796 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
5797 * </dl>
5798 *
5799 * @param <R>
5800 * the type of items emitted by the resulting Observable
5801 * @param selector
5802 * the selector function, which can use the multicasted sequence as many times as needed, without
5803 * causing multiple subscriptions to the Observable
5804 * @return an Observable that emits items that are the results of invoking the selector on a
5805 * {@link ConnectableObservable} that shares a single subscription to the source Observable
5806 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
5807 */
5808 public final <R> Observable<R> replay(Func1<? super Observable<T>, ? extends Observable<R>> selector) {
5809 return create(new OnSubscribeMulticastSelector<T, T, R>(this, new Func0<Subject<T, T>>() {
5810 @Override
5811 public final Subject<T, T> call() {
5812 return ReplaySubject.create();
5813 }
5814 }, selector));
5815 }
5816
5817 /**
5818 * Returns an Observable that emits items that are the results of invoking a specified selector on items
5819 * emitted by a {@link ConnectableObservable} that shares a single subscription to the source Observable,
5820 * replaying {@code bufferSize} notifications.
5821 * <p>
5822 * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fn.png" alt="">
5823 * <dl>
5824 * <dt><b>Backpressure Support:</b></dt>
5825 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
5826 * multiple subscribers. Each child will need to manage backpressure independently using operators such
5827 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
5828 * <dt><b>Scheduler:</b></dt>
5829 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
5830 * </dl>
5831 *
5832 * @param <R>
5833 * the type of items emitted by the resulting Observable
5834 * @param selector
5835 * the selector function, which can use the multicasted sequence as many times as needed, without
5836 * causing multiple subscriptions to the Observable
5837 * @param bufferSize
5838 * the buffer size that limits the number of items the connectable observable can replay
5839 * @return an Observable that emits items that are the results of invoking the selector on items emitted by
5840 * a {@link ConnectableObservable} that shares a single subscription to the source Observable
5841 * replaying no more than {@code bufferSize} items
5842 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
5843 */
5844 public final <R> Observable<R> replay(Func1<? super Observable<T>, ? extends Observable<R>> selector, final int bufferSize) {
5845 return create(new OnSubscribeMulticastSelector<T, T, R>(this, new Func0<Subject<T, T>>() {
5846 @Override
5847 public final Subject<T, T> call() {
5848 return ReplaySubject.<T>createWithSize(bufferSize);
5849 }
5850 }, selector));
5851 }
5852
5853 /**
5854 * Returns an Observable that emits items that are the results of invoking a specified selector on items
5855 * emitted by a {@link ConnectableObservable} that shares a single subscription to the source Observable,
5856 * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
5857 * <p>
5858 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fnt.png" alt="">
5859 * <dl>
5860 * <dt><b>Backpressure Support:</b></dt>
5861 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
5862 * multiple subscribers. Each child will need to manage backpressure independently using operators such
5863 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
5864 * <dt><b>Scheduler:</b></dt>
5865 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
5866 * </dl>
5867 *
5868 * @param <R>
5869 * the type of items emitted by the resulting Observable
5870 * @param selector
5871 * a selector function, which can use the multicasted sequence as many times as needed, without
5872 * causing multiple subscriptions to the Observable
5873 * @param bufferSize
5874 * the buffer size that limits the number of items the connectable observable can replay
5875 * @param time
5876 * the duration of the window in which the replayed items must have been emitted
5877 * @param unit
5878 * the time unit of {@code time}
5879 * @return an Observable that emits items that are the results of invoking the selector on items emitted by
5880 * a {@link ConnectableObservable} that shares a single subscription to the source Observable, and
5881 * replays no more than {@code bufferSize} items that were emitted within the window defined by
5882 * {@code time}
5883 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
5884 */
5885 public final <R> Observable<R> replay(Func1<? super Observable<T>, ? extends Observable<R>> selector, int bufferSize, long time, TimeUnit unit) {
5886 return replay(selector, bufferSize, time, unit, Schedulers.computation());
5887 }
5888
5889 /**
5890 * Returns an Observable that emits items that are the results of invoking a specified selector on items
5891 * emitted by a {@link ConnectableObservable} that shares a single subscription to the source Observable,
5892 * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
5893 * <p>
5894 * <img width="640" height="445" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fnts.png" alt="">
5895 * <dl>
5896 * <dt><b>Backpressure Support:</b></dt>
5897 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
5898 * multiple subscribers. Each child will need to manage backpressure independently using operators such
5899 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
5900 * <dt><b>Scheduler:</b></dt>
5901 * <dd>you specify which {@link Scheduler} this operator will use</dd>
5902 * </dl>
5903 *
5904 * @param <R>
5905 * the type of items emitted by the resulting Observable
5906 * @param selector
5907 * a selector function, which can use the multicasted sequence as many times as needed, without
5908 * causing multiple subscriptions to the Observable
5909 * @param bufferSize
5910 * the buffer size that limits the number of items the connectable observable can replay
5911 * @param time
5912 * the duration of the window in which the replayed items must have been emitted
5913 * @param unit
5914 * the time unit of {@code time}
5915 * @param scheduler
5916 * the Scheduler that is the time source for the window
5917 * @return an Observable that emits items that are the results of invoking the selector on items emitted by
5918 * a {@link ConnectableObservable} that shares a single subscription to the source Observable, and
5919 * replays no more than {@code bufferSize} items that were emitted within the window defined by
5920 * {@code time}
5921 * @throws IllegalArgumentException
5922 * if {@code bufferSize} is less than zero
5923 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
5924 */
5925 public final <R> Observable<R> replay(Func1<? super Observable<T>, ? extends Observable<R>> selector, final int bufferSize, final long time, final TimeUnit unit, final Scheduler scheduler) {
5926 if (bufferSize < 0) {
5927 throw new IllegalArgumentException("bufferSize < 0");
5928 }
5929 return create(new OnSubscribeMulticastSelector<T, T, R>(this, new Func0<Subject<T, T>>() {
5930 @Override
5931 public final Subject<T, T> call() {
5932 return ReplaySubject.<T>createWithTimeAndSize(time, unit, bufferSize, scheduler);
5933 }
5934 }, selector));
5935 }
5936
5937 /**
5938 * Returns an Observable that emits items that are the results of invoking a specified selector on items
5939 * emitted by a {@link ConnectableObservable} that shares a single subscription to the source Observable,
5940 * replaying a maximum of {@code bufferSize} items.
5941 * <p>
5942 * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fns.png" alt="">
5943 * <dl>
5944 * <dt><b>Backpressure Support:</b></dt>
5945 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
5946 * multiple subscribers. Each child will need to manage backpressure independently using operators such
5947 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
5948 * <dt><b>Scheduler:</b></dt>
5949 * <dd>you specify which {@link Scheduler} this operator will use</dd>
5950 * </dl>
5951 *
5952 * @param <R>
5953 * the type of items emitted by the resulting Observable
5954 * @param selector
5955 * a selector function, which can use the multicasted sequence as many times as needed, without
5956 * causing multiple subscriptions to the Observable
5957 * @param bufferSize
5958 * the buffer size that limits the number of items the connectable observable can replay
5959 * @param scheduler
5960 * the Scheduler on which the replay is observed
5961 * @return an Observable that emits items that are the results of invoking the selector on items emitted by
5962 * a {@link ConnectableObservable} that shares a single subscription to the source Observable,
5963 * replaying no more than {@code bufferSize} notifications
5964 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
5965 */
5966 public final <R> Observable<R> replay(Func1<? super Observable<T>, ? extends Observable<R>> selector, final int bufferSize, final Scheduler scheduler) {
5967 return create(new OnSubscribeMulticastSelector<T, T, R>(this, new Func0<Subject<T, T>>() {
5968 @Override
5969 public final Subject<T, T> call() {
5970 return OperatorReplay.<T> createScheduledSubject(ReplaySubject.<T>createWithSize(bufferSize), scheduler);
5971 }
5972 }, selector));
5973 }
5974
5975 /**
5976 * Returns an Observable that emits items that are the results of invoking a specified selector on items
5977 * emitted by a {@link ConnectableObservable} that shares a single subscription to the source Observable,
5978 * replaying all items that were emitted within a specified time window.
5979 * <p>
5980 * <img width="640" height="435" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.ft.png" alt="">
5981 * <dl>
5982 * <dt><b>Backpressure Support:</b></dt>
5983 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
5984 * multiple subscribers. Each child will need to manage backpressure independently using operators such
5985 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
5986 * <dt><b>Scheduler:</b></dt>
5987 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
5988 * </dl>
5989 *
5990 * @param <R>
5991 * the type of items emitted by the resulting Observable
5992 * @param selector
5993 * a selector function, which can use the multicasted sequence as many times as needed, without
5994 * causing multiple subscriptions to the Observable
5995 * @param time
5996 * the duration of the window in which the replayed items must have been emitted
5997 * @param unit
5998 * the time unit of {@code time}
5999 * @return an Observable that emits items that are the results of invoking the selector on items emitted by
6000 * a {@link ConnectableObservable} that shares a single subscription to the source Observable,
6001 * replaying all items that were emitted within the window defined by {@code time}
6002 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6003 */
6004 public final <R> Observable<R> replay(Func1<? super Observable<T>, ? extends Observable<R>> selector, long time, TimeUnit unit) {
6005 return replay(selector, time, unit, Schedulers.computation());
6006 }
6007
6008 /**
6009 * Returns an Observable that emits items that are the results of invoking a specified selector on items
6010 * emitted by a {@link ConnectableObservable} that shares a single subscription to the source Observable,
6011 * replaying all items that were emitted within a specified time window.
6012 * <p>
6013 * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fts.png" alt="">
6014 * <dl>
6015 * <dt><b>Backpressure Support:</b></dt>
6016 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6017 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6018 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6019 * <dt><b>Scheduler:</b></dt>
6020 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6021 * </dl>
6022 *
6023 * @param <R>
6024 * the type of items emitted by the resulting Observable
6025 * @param selector
6026 * a selector function, which can use the multicasted sequence as many times as needed, without
6027 * causing multiple subscriptions to the Observable
6028 * @param time
6029 * the duration of the window in which the replayed items must have been emitted
6030 * @param unit
6031 * the time unit of {@code time}
6032 * @param scheduler
6033 * the scheduler that is the time source for the window
6034 * @return an Observable that emits items that are the results of invoking the selector on items emitted by
6035 * a {@link ConnectableObservable} that shares a single subscription to the source Observable,
6036 * replaying all items that were emitted within the window defined by {@code time}
6037 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6038 */
6039 public final <R> Observable<R> replay(Func1<? super Observable<T>, ? extends Observable<R>> selector, final long time, final TimeUnit unit, final Scheduler scheduler) {
6040 return create(new OnSubscribeMulticastSelector<T, T, R>(this, new Func0<Subject<T, T>>() {
6041 @Override
6042 public final Subject<T, T> call() {
6043 return ReplaySubject.<T>createWithTime(time, unit, scheduler);
6044 }
6045 }, selector));
6046 }
6047
6048 /**
6049 * Returns an Observable that emits items that are the results of invoking a specified selector on items
6050 * emitted by a {@link ConnectableObservable} that shares a single subscription to the source Observable.
6051 * <p>
6052 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fs.png" alt="">
6053 * <dl>
6054 * <dt><b>Backpressure Support:</b></dt>
6055 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6056 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6057 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6058 * <dt><b>Scheduler:</b></dt>
6059 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6060 * </dl>
6061 *
6062 * @param <R>
6063 * the type of items emitted by the resulting Observable
6064 * @param selector
6065 * a selector function, which can use the multicasted sequence as many times as needed, without
6066 * causing multiple subscriptions to the Observable
6067 * @param scheduler
6068 * the Scheduler where the replay is observed
6069 * @return an Observable that emits items that are the results of invoking the selector on items emitted by
6070 * a {@link ConnectableObservable} that shares a single subscription to the source Observable,
6071 * replaying all items
6072 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6073 */
6074 public final <R> Observable<R> replay(Func1<? super Observable<T>, ? extends Observable<R>> selector, final Scheduler scheduler) {
6075 return create(new OnSubscribeMulticastSelector<T, T, R>(this, new Func0<Subject<T, T>>() {
6076 @Override
6077 public final Subject<T, T> call() {
6078 return OperatorReplay.createScheduledSubject(ReplaySubject.<T> create(), scheduler);
6079 }
6080 }, selector));
6081 }
6082
6083 /**
6084 * Returns a {@link ConnectableObservable} that shares a single subscription to the source Observable that
6085 * replays at most {@code bufferSize} items emitted by that Observable. A Connectable Observable resembles
6086 * an ordinary Observable, except that it does not begin emitting items when it is subscribed to, but only
6087 * when its {@code connect} method is called.
6088 * <p>
6089 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.n.png" alt="">
6090 * <dl>
6091 * <dt><b>Backpressure Support:</b></dt>
6092 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6093 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6094 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6095 * <dt><b>Scheduler:</b></dt>
6096 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
6097 * </dl>
6098 *
6099 * @param bufferSize
6100 * the buffer size that limits the number of items that can be replayed
6101 * @return a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6102 * replays at most {@code bufferSize} items emitted by that Observable
6103 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6104 */
6105 public final ConnectableObservable<T> replay(final int bufferSize) {
6106 return new OperatorMulticast<T, T>(this, new Func0<Subject<? super T, ? extends T>>() {
6107
6108 @Override
6109 public Subject<? super T, ? extends T> call() {
6110 return ReplaySubject.<T>createWithSize(bufferSize);
6111 }
6112
6113 });
6114 }
6115
6116 /**
6117 * Returns a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6118 * replays at most {@code bufferSize} items that were emitted during a specified time window. A Connectable
6119 * Observable resembles an ordinary Observable, except that it does not begin emitting items when it is
6120 * subscribed to, but only when its {@code connect} method is called.
6121 * <p>
6122 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.nt.png" alt="">
6123 * <dl>
6124 * <dt><b>Backpressure Support:</b></dt>
6125 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6126 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6127 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6128 * <dt><b>Scheduler:</b></dt>
6129 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
6130 * </dl>
6131 *
6132 * @param bufferSize
6133 * the buffer size that limits the number of items that can be replayed
6134 * @param time
6135 * the duration of the window in which the replayed items must have been emitted
6136 * @param unit
6137 * the time unit of {@code time}
6138 * @return a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6139 * replays at most {@code bufferSize} items that were emitted during the window defined by
6140 * {@code time}
6141 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6142 */
6143 public final ConnectableObservable<T> replay(int bufferSize, long time, TimeUnit unit) {
6144 return replay(bufferSize, time, unit, Schedulers.computation());
6145 }
6146
6147 /**
6148 * Returns a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6149 * that replays a maximum of {@code bufferSize} items that are emitted within a specified time window. A
6150 * Connectable Observable resembles an ordinary Observable, except that it does not begin emitting items
6151 * when it is subscribed to, but only when its {@code connect} method is called.
6152 * <p>
6153 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.nts.png" alt="">
6154 * <dl>
6155 * <dt><b>Backpressure Support:</b></dt>
6156 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6157 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6158 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6159 * <dt><b>Scheduler:</b></dt>
6160 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6161 * </dl>
6162 *
6163 * @param bufferSize
6164 * the buffer size that limits the number of items that can be replayed
6165 * @param time
6166 * the duration of the window in which the replayed items must have been emitted
6167 * @param unit
6168 * the time unit of {@code time}
6169 * @param scheduler
6170 * the scheduler that is used as a time source for the window
6171 * @return a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6172 * replays at most {@code bufferSize} items that were emitted during the window defined by
6173 * {@code time}
6174 * @throws IllegalArgumentException
6175 * if {@code bufferSize} is less than zero
6176 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6177 */
6178 public final ConnectableObservable<T> replay(final int bufferSize, final long time, final TimeUnit unit, final Scheduler scheduler) {
6179 if (bufferSize < 0) {
6180 throw new IllegalArgumentException("bufferSize < 0");
6181 }
6182 return new OperatorMulticast<T, T>(this, new Func0<Subject<? super T, ? extends T>>() {
6183
6184 @Override
6185 public Subject<? super T, ? extends T> call() {
6186 return ReplaySubject.<T>createWithTimeAndSize(time, unit, bufferSize, scheduler);
6187 }
6188
6189 });
6190 }
6191
6192 /**
6193 * Returns a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6194 * replays at most {@code bufferSize} items emitted by that Observable. A Connectable Observable resembles
6195 * an ordinary Observable, except that it does not begin emitting items when it is subscribed to, but only
6196 * when its {@code connect} method is called.
6197 * <p>
6198 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.ns.png" alt="">
6199 * <dl>
6200 * <dt><b>Backpressure Support:</b></dt>
6201 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6202 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6203 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6204 * <dt><b>Scheduler:</b></dt>
6205 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6206 * </dl>
6207 *
6208 * @param bufferSize
6209 * the buffer size that limits the number of items that can be replayed
6210 * @param scheduler
6211 * the scheduler on which the Observers will observe the emitted items
6212 * @return a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6213 * replays at most {@code bufferSize} items that were emitted by the Observable
6214 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6215 */
6216 public final ConnectableObservable<T> replay(final int bufferSize, final Scheduler scheduler) {
6217 return new OperatorMulticast<T, T>(this, new Func0<Subject<? super T, ? extends T>>() {
6218
6219 @Override
6220 public Subject<? super T, ? extends T> call() {
6221 return OperatorReplay.createScheduledSubject(ReplaySubject.<T>createWithSize(bufferSize), scheduler);
6222 }
6223
6224 });
6225 }
6226
6227 /**
6228 * Returns a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6229 * replays all items emitted by that Observable within a specified time window. A Connectable Observable
6230 * resembles an ordinary Observable, except that it does not begin emitting items when it is subscribed to,
6231 * but only when its {@code connect} method is called.
6232 * <p>
6233 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.t.png" alt="">
6234 * <dl>
6235 * <dt><b>Backpressure Support:</b></dt>
6236 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6237 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6238 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6239 * <dt><b>Scheduler:</b></dt>
6240 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
6241 * </dl>
6242 *
6243 * @param time
6244 * the duration of the window in which the replayed items must have been emitted
6245 * @param unit
6246 * the time unit of {@code time}
6247 * @return a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6248 * replays the items that were emitted during the window defined by {@code time}
6249 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6250 */
6251 public final ConnectableObservable<T> replay(long time, TimeUnit unit) {
6252 return replay(time, unit, Schedulers.computation());
6253 }
6254
6255 /**
6256 * Returns a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6257 * replays all items emitted by that Observable within a specified time window. A Connectable Observable
6258 * resembles an ordinary Observable, except that it does not begin emitting items when it is subscribed to,
6259 * but only when its {@code connect} method is called.
6260 * <p>
6261 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.ts.png" alt="">
6262 * <dl>
6263 * <dt><b>Backpressure Support:</b></dt>
6264 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6265 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6266 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6267 * <dt><b>Scheduler:</b></dt>
6268 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6269 * </dl>
6270 *
6271 * @param time
6272 * the duration of the window in which the replayed items must have been emitted
6273 * @param unit
6274 * the time unit of {@code time}
6275 * @param scheduler
6276 * the Scheduler that is the time source for the window
6277 * @return a {@link ConnectableObservable} that shares a single subscription to the source Observable and
6278 * replays the items that were emitted during the window defined by {@code time}
6279 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6280 */
6281 public final ConnectableObservable<T> replay(final long time, final TimeUnit unit, final Scheduler scheduler) {
6282 return new OperatorMulticast<T, T>(this, new Func0<Subject<? super T, ? extends T>>() {
6283
6284 @Override
6285 public Subject<? super T, ? extends T> call() {
6286 return ReplaySubject.<T>createWithTime(time, unit, scheduler);
6287 }
6288
6289 });
6290 }
6291
6292 /**
6293 * Returns a {@link ConnectableObservable} that shares a single subscription to the source Observable that
6294 * will replay all of its items and notifications to any future {@link Observer} on the given
6295 * {@link Scheduler}. A Connectable Observable resembles an ordinary Observable, except that it does not
6296 * begin emitting items when it is subscribed to, but only when its {@code connect} method is called.
6297 * <p>
6298 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.s.png" alt="">
6299 * <dl>
6300 * <dt><b>Backpressure Support:</b></dt>
6301 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6302 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6303 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6304 * <dt><b>Scheduler:</b></dt>
6305 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6306 * </dl>
6307 *
6308 * @param scheduler
6309 * the Scheduler on which the Observers will observe the emitted items
6310 * @return a {@link ConnectableObservable} that shares a single subscription to the source Observable that
6311 * will replay all of its items and notifications to any future {@link Observer} on the given
6312 * {@link Scheduler}
6313 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6314 */
6315 public final ConnectableObservable<T> replay(final Scheduler scheduler) {
6316 return new OperatorMulticast<T, T>(this, new Func0<Subject<? super T, ? extends T>>() {
6317
6318 @Override
6319 public Subject<? super T, ? extends T> call() {
6320 return OperatorReplay.createScheduledSubject(ReplaySubject.<T> create(), scheduler);
6321 }
6322
6323 });
6324 }
6325
6326 /**
6327 * Returns an Observable that mirrors the source Observable, resubscribing to it if it calls {@code onError}
6328 * (infinite retry count).
6329 * <p>
6330 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.png" alt="">
6331 * <p>
6332 * If the source Observable calls {@link Observer#onError}, this method will resubscribe to the source
6333 * Observable rather than propagating the {@code onError} call.
6334 * <p>
6335 * Any and all items emitted by the source Observable will be emitted by the resulting Observable, even
6336 * those emitted during failed subscriptions. For example, if an Observable fails at first but emits
6337 * {@code [1, 2]} then succeeds the second time and emits {@code [1, 2, 3, 4, 5]} then the complete sequence
6338 * of emissions and notifications would be {@code [1, 2, 1, 2, 3, 4, 5, onCompleted]}.
6339 * <dl>
6340 * <dt><b>Scheduler:</b></dt>
6341 * <dd>{@code retry} operates by default on the {@code trampoline} {@link Scheduler}.</dd>
6342 * </dl>
6343 *
6344 * @return the source Observable modified with retry logic
6345 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
6346 */
6347 public final Observable<T> retry() {
6348 return OnSubscribeRedo.<T>retry(this);
6349 }
6350
6351 /**
6352 * Returns an Observable that mirrors the source Observable, resubscribing to it if it calls {@code onError}
6353 * up to a specified number of retries.
6354 * <p>
6355 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.png" alt="">
6356 * <p>
6357 * If the source Observable calls {@link Observer#onError}, this method will resubscribe to the source
6358 * Observable for a maximum of {@code count} resubscriptions rather than propagating the
6359 * {@code onError} call.
6360 * <p>
6361 * Any and all items emitted by the source Observable will be emitted by the resulting Observable, even
6362 * those emitted during failed subscriptions. For example, if an Observable fails at first but emits
6363 * {@code [1, 2]} then succeeds the second time and emits {@code [1, 2, 3, 4, 5]} then the complete sequence
6364 * of emissions and notifications would be {@code [1, 2, 1, 2, 3, 4, 5, onCompleted]}.
6365 * <dl>
6366 * <dt><b>Scheduler:</b></dt>
6367 * <dd>{@code retry} operates by default on the {@code trampoline} {@link Scheduler}.</dd>
6368 * </dl>
6369 *
6370 * @param count
6371 * number of retry attempts before failing
6372 * @return the source Observable modified with retry logic
6373 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
6374 */
6375 public final Observable<T> retry(final long count) {
6376 return OnSubscribeRedo.<T>retry(this, count);
6377 }
6378
6379 /**
6380 * Returns an Observable that mirrors the source Observable, resubscribing to it if it calls {@code onError}
6381 * and the predicate returns true for that specific exception and retry count.
6382 * <p>
6383 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.png" alt="">
6384 * <dl>
6385 * <dt><b>Scheduler:</b></dt>
6386 * <dd>{@code retry} operates by default on the {@code trampoline} {@link Scheduler}.</dd>
6387 * </dl>
6388 *
6389 * @param predicate
6390 * the predicate that determines if a resubscription may happen in case of a specific exception
6391 * and retry count
6392 * @return the source Observable modified with retry logic
6393 * @see #retry()
6394 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
6395 */
6396 public final Observable<T> retry(Func2<Integer, Throwable, Boolean> predicate) {
6397 return nest().lift(new OperatorRetryWithPredicate<T>(predicate));
6398 }
6399
6400 /**
6401 * Returns an Observable that emits the same values as the source observable with the exception of an
6402 * {@code onError}. An {@code onError} notification from the source will result in the emission of a
6403 * {@link Throwable} item to the Observable provided as an argument to the {@code notificationHandler}
6404 * function. If that Observable calls {@code onComplete} or {@code onError} then {@code retry} will call
6405 * {@code onCompleted} or {@code onError} on the child subscription. Otherwise, this Observable will
6406 * resubscribe to the source Observable.
6407 * <p>
6408 * <img width="640" height="430" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retryWhen.f.png" alt="">
6409 *
6410 * Example:
6411 *
6412 * This retries 3 times, each time incrementing the number of seconds it waits.
6413 *
6414 * <pre> {@code
6415 * Observable.create((Subscriber<? super String> s) -> {
6416 * System.out.println("subscribing");
6417 * s.onError(new RuntimeException("always fails"));
6418 * }).retryWhen(attempts -> {
6419 * return attempts.zipWith(Observable.range(1, 3), (n, i) -> i).flatMap(i -> {
6420 * System.out.println("delay retry by " + i + " second(s)");
6421 * return Observable.timer(i, TimeUnit.SECONDS);
6422 * });
6423 * }).toBlocking().forEach(System.out::println);
6424 * } </pre>
6425 *
6426 * Output is:
6427 *
6428 * <pre> {@code
6429 * subscribing
6430 * delay retry by 1 second(s)
6431 * subscribing
6432 * delay retry by 2 second(s)
6433 * subscribing
6434 * delay retry by 3 second(s)
6435 * subscribing
6436 * } </pre>
6437 * <dl>
6438 * <dt><b>Scheduler:</b></dt>
6439 * <dd>{@code retryWhen} operates by default on the {@code trampoline} {@link Scheduler}.</dd>
6440 * </dl>
6441 *
6442 * @param notificationHandler
6443 * receives an Observable of notifications with which a user can complete or error, aborting the
6444 * retry
6445 * @return the source Observable modified with retry logic
6446 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
6447 */
6448 public final Observable<T> retryWhen(final Func1<? super Observable<? extends Throwable>, ? extends Observable<?>> notificationHandler) {
6449 Func1<? super Observable<? extends Notification<?>>, ? extends Observable<?>> dematerializedNotificationHandler = new Func1<Observable<? extends Notification<?>>, Observable<?>>() {
6450 @Override
6451 public Observable<?> call(Observable<? extends Notification<?>> notifications) {
6452 return notificationHandler.call(notifications.map(new Func1<Notification<?>, Throwable>() {
6453 @Override
6454 public Throwable call(Notification<?> notification) {
6455 return notification.getThrowable();
6456 }
6457 }));
6458 }
6459 };
6460 return OnSubscribeRedo.<T> retry(this, dematerializedNotificationHandler);
6461 }
6462
6463 /**
6464 * Returns an Observable that emits the same values as the source observable with the exception of an
6465 * {@code onError}. An {@code onError} will cause the emission of the {@link Throwable} that cause the
6466 * error to the Observable returned from {@code notificationHandler}. If that Observable calls
6467 * {@code onComplete} or {@code onError} then {@code retry} will call {@code onCompleted} or {@code onError}
6468 * on the child subscription. Otherwise, this Observable will resubscribe to the source observable, on a
6469 * particular Scheduler.
6470 * <p>
6471 * <img width="640" height="430" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retryWhen.f.png" alt="">
6472 * <p>
6473 * <dl>
6474 * <dt><b>Scheduler:</b></dt>
6475 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6476 * </dl>
6477 *
6478 * @param notificationHandler
6479 * receives an Observable of notifications with which a user can complete or error, aborting the
6480 * retry
6481 * @param scheduler
6482 * the {@link Scheduler} on which to subscribe to the source Observable
6483 * @return the source Observable modified with retry logic
6484 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
6485 */
6486 public final Observable<T> retryWhen(final Func1<? super Observable<? extends Throwable>, ? extends Observable<?>> notificationHandler, Scheduler scheduler) {
6487 Func1<? super Observable<? extends Notification<?>>, ? extends Observable<?>> dematerializedNotificationHandler = new Func1<Observable<? extends Notification<?>>, Observable<?>>() {
6488 @Override
6489 public Observable<?> call(Observable<? extends Notification<?>> notifications) {
6490 return notificationHandler.call(notifications.map(new Func1<Notification<?>, Throwable>() {
6491 @Override
6492 public Throwable call(Notification<?> notification) {
6493 return notification.getThrowable();
6494 }
6495 }));
6496 }
6497 };
6498 return OnSubscribeRedo.<T> retry(this, dematerializedNotificationHandler, scheduler);
6499 }
6500
6501 /**
6502 * Returns an Observable that emits the most recently emitted item (if any) emitted by the source Observable
6503 * within periodic time intervals.
6504 * <p>
6505 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.png" alt="">
6506 * <dl>
6507 * <dt><b>Backpressure Support:</b></dt>
6508 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
6509 * <dt><b>Scheduler:</b></dt>
6510 * <dd>{@code sample} operates by default on the {@code computation} {@link Scheduler}.</dd>
6511 * </dl>
6512 *
6513 * @param period
6514 * the sampling rate
6515 * @param unit
6516 * the {@link TimeUnit} in which {@code period} is defined
6517 * @return an Observable that emits the results of sampling the items emitted by the source Observable at
6518 * the specified time interval
6519 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
6520 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
6521 * @see #throttleLast(long, TimeUnit)
6522 */
6523 public final Observable<T> sample(long period, TimeUnit unit) {
6524 return sample(period, unit, Schedulers.computation());
6525 }
6526
6527 /**
6528 * Returns an Observable that emits the most recently emitted item (if any) emitted by the source Observable
6529 * within periodic time intervals, where the intervals are defined on a particular Scheduler.
6530 * <p>
6531 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.s.png" alt="">
6532 * <dl>
6533 * <dt><b>Backpressure Support:</b></dt>
6534 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
6535 * <dt><b>Scheduler:</b></dt>
6536 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6537 * </dl>
6538 *
6539 * @param period
6540 * the sampling rate
6541 * @param unit
6542 * the {@link TimeUnit} in which {@code period} is defined
6543 * @param scheduler
6544 * the {@link Scheduler} to use when sampling
6545 * @return an Observable that emits the results of sampling the items emitted by the source Observable at
6546 * the specified time interval
6547 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
6548 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
6549 * @see #throttleLast(long, TimeUnit, Scheduler)
6550 */
6551 public final Observable<T> sample(long period, TimeUnit unit, Scheduler scheduler) {
6552 return lift(new OperatorSampleWithTime<T>(period, unit, scheduler));
6553 }
6554
6555 /**
6556 * Returns an Observable that, when the specified {@code sampler} Observable emits an item or completes,
6557 * emits the most recently emitted item (if any) emitted by the source Observable since the previous
6558 * emission from the {@code sampler} Observable.
6559 * <p>
6560 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.o.png" alt="">
6561 * <dl>
6562 * <dt><b>Backpressure Support:</b></dt>
6563 * <dd>This operator does not support backpressure as it uses the emissions of the {@code sampler}
6564 * Observable to control data flow.</dd>
6565 * <dt><b>Scheduler:</b></dt>
6566 * <dd>This version of {@code sample} does not operate by default on a particular {@link Scheduler}.</dd>
6567 * </dl>
6568 *
6569 * @param sampler
6570 * the Observable to use for sampling the source Observable
6571 * @return an Observable that emits the results of sampling the items emitted by this Observable whenever
6572 * the {@code sampler} Observable emits an item or completes
6573 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
6574 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
6575 */
6576 public final <U> Observable<T> sample(Observable<U> sampler) {
6577 return lift(new OperatorSampleWithObservable<T, U>(sampler));
6578 }
6579
6580 /**
6581 * Returns an Observable that applies a specified accumulator function to the first item emitted by a source
6582 * Observable, then feeds the result of that function along with the second item emitted by the source
6583 * Observable into the same function, and so on until all items have been emitted by the source Observable,
6584 * emitting the result of each of these iterations.
6585 * <p>
6586 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/scan.png" alt="">
6587 * <p>
6588 * This sort of function is sometimes called an accumulator.
6589 * <dl>
6590 * <dt><b>Scheduler:</b></dt>
6591 * <dd>{@code scan} does not operate by default on a particular {@link Scheduler}.</dd>
6592 * </dl>
6593 *
6594 * @param accumulator
6595 * an accumulator function to be invoked on each item emitted by the source Observable, whose
6596 * result will be emitted to {@link Observer}s via {@link Observer#onNext onNext} and used in the
6597 * next accumulator call
6598 * @return an Observable that emits the results of each call to the accumulator function
6599 * @see <a href="http://reactivex.io/documentation/operators/scan.html">ReactiveX operators documentation: Scan</a>
6600 */
6601 public final Observable<T> scan(Func2<T, T, T> accumulator) {
6602 return lift(new OperatorScan<T, T>(accumulator));
6603 }
6604
6605 /**
6606 * Returns an Observable that applies a specified accumulator function to the first item emitted by a source
6607 * Observable and a seed value, then feeds the result of that function along with the second item emitted by
6608 * the source Observable into the same function, and so on until all items have been emitted by the source
6609 * Observable, emitting the result of each of these iterations.
6610 * <p>
6611 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/scanSeed.png" alt="">
6612 * <p>
6613 * This sort of function is sometimes called an accumulator.
6614 * <p>
6615 * Note that the Observable that results from this method will emit {@code initialValue} as its first
6616 * emitted item.
6617 * <dl>
6618 * <dt><b>Scheduler:</b></dt>
6619 * <dd>{@code scan} does not operate by default on a particular {@link Scheduler}.</dd>
6620 * </dl>
6621 *
6622 * @param initialValue
6623 * the initial (seed) accumulator item
6624 * @param accumulator
6625 * an accumulator function to be invoked on each item emitted by the source Observable, whose
6626 * result will be emitted to {@link Observer}s via {@link Observer#onNext onNext} and used in the
6627 * next accumulator call
6628 * @return an Observable that emits {@code initialValue} followed by the results of each call to the
6629 * accumulator function
6630 * @see <a href="http://reactivex.io/documentation/operators/scan.html">ReactiveX operators documentation: Scan</a>
6631 */
6632 public final <R> Observable<R> scan(R initialValue, Func2<R, ? super T, R> accumulator) {
6633 return lift(new OperatorScan<R, T>(initialValue, accumulator));
6634 }
6635
6636 /**
6637 * Forces an Observable's emissions and notifications to be serialized and for it to obey the Rx contract
6638 * in other ways.
6639 * <p>
6640 * It is possible for an Observable to invoke its Subscribers' methods asynchronously, perhaps from
6641 * different threads. This could make such an Observable poorly-behaved, in that it might try to invoke
6642 * {@code onCompleted} or {@code onError} before one of its {@code onNext} invocations, or it might call
6643 * {@code onNext} from two different threads concurrently. You can force such an Observable to be
6644 * well-behaved and sequential by applying the {@code serialize} method to it.
6645 * <p>
6646 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/synchronize.png" alt="">
6647 * <dl>
6648 * <dt><b>Scheduler:</b></dt>
6649 * <dd>{@code serialize} does not operate by default on a particular {@link Scheduler}.</dd>
6650 * </dl>
6651 *
6652 * @return an {@link Observable} that is guaranteed to be well-behaved and to make only serialized calls to
6653 * its observers
6654 * @see <a href="http://reactivex.io/documentation/operators/serialize.html">ReactiveX operators documentation: Serialize</a>
6655 */
6656 public final Observable<T> serialize() {
6657 return lift(OperatorSerialize.<T>instance());
6658 }
6659
6660 /**
6661 * Returns a new {@link Observable} that multicasts (shares) the original {@link Observable}. As long as
6662 * there is at least one {@link Subscriber} this {@link Observable} will be subscribed and emitting data.
6663 * When all subscribers have unsubscribed it will unsubscribe from the source {@link Observable}.
6664 * <p>
6665 * This is an alias for {@link #publish()}.{@link ConnectableObservable#refCount()}.
6666 * <p>
6667 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishRefCount.png" alt="">
6668 * <dl>
6669 * <dt><b>Backpressure Support:</b></dt>
6670 * <dd>This operator does not support backpressure because multicasting means the stream is "hot" with
6671 * multiple subscribers. Each child will need to manage backpressure independently using operators such
6672 * as {@link #onBackpressureDrop} and {@link #onBackpressureBuffer}.</dd>
6673 * <dt><b>Scheduler:</b></dt>
6674 * <dd>{@code share} does not operate by default on a particular {@link Scheduler}.</dd>
6675 * </dl>
6676 *
6677 * @return an {@code Observable} that upon connection causes the source {@code Observable} to emit items
6678 * to its {@link Observer}s
6679 * @see <a href="http://reactivex.io/documentation/operators/refcount.html">ReactiveX operators documentation: RefCount</a>
6680 */
6681 public final Observable<T> share() {
6682 return publish().refCount();
6683 }
6684
6685 /**
6686 * Returns an Observable that emits the single item emitted by the source Observable, if that Observable
6687 * emits only a single item. If the source Observable emits more than one item or no items, notify of an
6688 * {@code IllegalArgumentException} or {@code NoSuchElementException} respectively.
6689 * <p>
6690 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/single.png" alt="">
6691 * <dl>
6692 * <dt><b>Scheduler:</b></dt>
6693 * <dd>{@code single} does not operate by default on a particular {@link Scheduler}.</dd>
6694 * </dl>
6695 *
6696 * @return an Observable that emits the single item emitted by the source Observable
6697 * @throws IllegalArgumentException
6698 * if the source emits more than one item
6699 * @throws NoSuchElementException
6700 * if the source emits no items
6701 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
6702 */
6703 public final Observable<T> single() {
6704 return lift(new OperatorSingle<T>());
6705 }
6706
6707 /**
6708 * Returns an Observable that emits the single item emitted by the source Observable that matches a
6709 * specified predicate, if that Observable emits one such item. If the source Observable emits more than one
6710 * such item or no such items, notify of an {@code IllegalArgumentException} or
6711 * {@code NoSuchElementException} respectively.
6712 * <p>
6713 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/single.p.png" alt="">
6714 * <dl>
6715 * <dt><b>Scheduler:</b></dt>
6716 * <dd>{@code single} does not operate by default on a particular {@link Scheduler}.</dd>
6717 * </dl>
6718 *
6719 * @param predicate
6720 * a predicate function to evaluate items emitted by the source Observable
6721 * @return an Observable that emits the single item emitted by the source Observable that matches the
6722 * predicate
6723 * @throws IllegalArgumentException
6724 * if the source Observable emits more than one item that matches the predicate
6725 * @throws NoSuchElementException
6726 * if the source Observable emits no item that matches the predicate
6727 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
6728 */
6729 public final Observable<T> single(Func1<? super T, Boolean> predicate) {
6730 return filter(predicate).single();
6731 }
6732
6733 /**
6734 * Returns an Observable that emits the single item emitted by the source Observable, if that Observable
6735 * emits only a single item, or a default item if the source Observable emits no items. If the source
6736 * Observable emits more than one item, throw an {@code IllegalArgumentException}.
6737 * <p>
6738 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrDefault.png" alt="">
6739 * <dl>
6740 * <dt><b>Scheduler:</b></dt>
6741 * <dd>{@code singleOrDefault} does not operate by default on a particular {@link Scheduler}.</dd>
6742 * </dl>
6743 *
6744 * @param defaultValue
6745 * a default value to emit if the source Observable emits no item
6746 * @return an Observable that emits the single item emitted by the source Observable, or a default item if
6747 * the source Observable is empty
6748 * @throws IllegalArgumentException
6749 * if the source Observable emits more than one item
6750 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
6751 */
6752 public final Observable<T> singleOrDefault(T defaultValue) {
6753 return lift(new OperatorSingle<T>(defaultValue));
6754 }
6755
6756 /**
6757 * Returns an Observable that emits the single item emitted by the source Observable that matches a
6758 * predicate, if that Observable emits only one such item, or a default item if the source Observable emits
6759 * no such items. If the source Observable emits more than one such item, throw an
6760 * {@code IllegalArgumentException}.
6761 * <p>
6762 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrDefault.p.png" alt="">
6763 * <dl>
6764 * <dt><b>Scheduler:</b></dt>
6765 * <dd>{@code singleOrDefault} does not operate by default on a particular {@link Scheduler}.</dd>
6766 * </dl>
6767 *
6768 * @param defaultValue
6769 * a default item to emit if the source Observable emits no matching items
6770 * @param predicate
6771 * a predicate function to evaluate items emitted by the source Observable
6772 * @return an Observable that emits the single item emitted by the source Observable that matches the
6773 * predicate, or the default item if no emitted item matches the predicate
6774 * @throws IllegalArgumentException
6775 * if the source Observable emits more than one item that matches the predicate
6776 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
6777 */
6778 public final Observable<T> singleOrDefault(T defaultValue, Func1<? super T, Boolean> predicate) {
6779 return filter(predicate).singleOrDefault(defaultValue);
6780 }
6781
6782 /**
6783 * Returns an Observable that skips the first {@code num} items emitted by the source Observable and emits
6784 * the remainder.
6785 * <p>
6786 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skip.png" alt="">
6787 * <dl>
6788 * <dt><b>Scheduler:</b></dt>
6789 * <dd>This version of {@code skip} does not operate by default on a particular {@link Scheduler}.</dd>
6790 * </dl>
6791 *
6792 * @param num
6793 * the number of items to skip
6794 * @return an Observable that is identical to the source Observable except that it does not emit the first
6795 * {@code num} items that the source Observable emits
6796 * @see <a href="http://reactivex.io/documentation/operators/skip.html">ReactiveX operators documentation: Skip</a>
6797 */
6798 public final Observable<T> skip(int num) {
6799 return lift(new OperatorSkip<T>(num));
6800 }
6801
6802 /**
6803 * Returns an Observable that skips values emitted by the source Observable before a specified time window
6804 * elapses.
6805 * <p>
6806 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skip.t.png" alt="">
6807 * <dl>
6808 * <dt><b>Scheduler:</b></dt>
6809 * <dd>This version of {@code skip} operates by default on the {@code computation} {@link Scheduler}.</dd>
6810 * </dl>
6811 *
6812 * @param time
6813 * the length of the time window to skip
6814 * @param unit
6815 * the time unit of {@code time}
6816 * @return an Observable that skips values emitted by the source Observable before the time window defined
6817 * by {@code time} elapses and the emits the remainder
6818 * @see <a href="http://reactivex.io/documentation/operators/skip.html">ReactiveX operators documentation: Skip</a>
6819 */
6820 public final Observable<T> skip(long time, TimeUnit unit) {
6821 return skip(time, unit, Schedulers.computation());
6822 }
6823
6824 /**
6825 * Returns an Observable that skips values emitted by the source Observable before a specified time window
6826 * on a specified {@link Scheduler} elapses.
6827 * <p>
6828 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skip.ts.png" alt="">
6829 * <dl>
6830 * <dt><b>Scheduler:</b></dt>
6831 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6832 * </dl>
6833 *
6834 * @param time
6835 * the length of the time window to skip
6836 * @param unit
6837 * the time unit of {@code time}
6838 * @param scheduler
6839 * the {@link Scheduler} on which the timed wait happens
6840 * @return an Observable that skips values emitted by the source Observable before the time window defined
6841 * by {@code time} and {@code scheduler} elapses, and then emits the remainder
6842 * @see <a href="http://reactivex.io/documentation/operators/skip.html">ReactiveX operators documentation: Skip</a>
6843 */
6844 public final Observable<T> skip(long time, TimeUnit unit, Scheduler scheduler) {
6845 return lift(new OperatorSkipTimed<T>(time, unit, scheduler));
6846 }
6847
6848 /**
6849 * Returns an Observable that drops a specified number of items from the end of the sequence emitted by the
6850 * source Observable.
6851 * <p>
6852 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.png" alt="">
6853 * <p>
6854 * This Observer accumulates a queue long enough to store the first {@code count} items. As more items are
6855 * received, items are taken from the front of the queue and emitted by the returned Observable. This causes
6856 * such items to be delayed.
6857 * <dl>
6858 * <dt><b>Scheduler:</b></dt>
6859 * <dd>This version of {@code skipLast} does not operate by default on a particular {@link Scheduler}.</dd>
6860 * </dl>
6861 *
6862 * @param count
6863 * number of items to drop from the end of the source sequence
6864 * @return an Observable that emits the items emitted by the source Observable except for the dropped ones
6865 * at the end
6866 * @throws IndexOutOfBoundsException
6867 * if {@code count} is less than zero
6868 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
6869 */
6870 public final Observable<T> skipLast(int count) {
6871 return lift(new OperatorSkipLast<T>(count));
6872 }
6873
6874 /**
6875 * Returns an Observable that drops items emitted by the source Observable during a specified time window
6876 * before the source completes.
6877 * <p>
6878 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.t.png" alt="">
6879 * <p>
6880 * Note: this action will cache the latest items arriving in the specified time window.
6881 * <dl>
6882 * <dt><b>Scheduler:</b></dt>
6883 * <dd>This version of {@code skipLast} operates by default on the {@code computation} {@link Scheduler}.</dd>
6884 * </dl>
6885 *
6886 * @param time
6887 * the length of the time window
6888 * @param unit
6889 * the time unit of {@code time}
6890 * @return an Observable that drops those items emitted by the source Observable in a time window before the
6891 * source completes defined by {@code time}
6892 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
6893 */
6894 public final Observable<T> skipLast(long time, TimeUnit unit) {
6895 return skipLast(time, unit, Schedulers.computation());
6896 }
6897
6898 /**
6899 * Returns an Observable that drops items emitted by the source Observable during a specified time window
6900 * (defined on a specified scheduler) before the source completes.
6901 * <p>
6902 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.ts.png" alt="">
6903 * <p>
6904 * Note: this action will cache the latest items arriving in the specified time window.
6905 * <dl>
6906 * <dt><b>Scheduler:</b></dt>
6907 * <dd>you specify which {@link Scheduler} this operator will use</dd>
6908 * </dl>
6909 *
6910 * @param time
6911 * the length of the time window
6912 * @param unit
6913 * the time unit of {@code time}
6914 * @param scheduler
6915 * the scheduler used as the time source
6916 * @return an Observable that drops those items emitted by the source Observable in a time window before the
6917 * source completes defined by {@code time} and {@code scheduler}
6918 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
6919 */
6920 public final Observable<T> skipLast(long time, TimeUnit unit, Scheduler scheduler) {
6921 return lift(new OperatorSkipLastTimed<T>(time, unit, scheduler));
6922 }
6923
6924 /**
6925 * Returns an Observable that skips items emitted by the source Observable until a second Observable emits
6926 * an item.
6927 * <p>
6928 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipUntil.png" alt="">
6929 * <dl>
6930 * <dt><b>Scheduler:</b></dt>
6931 * <dd>{@code skipUntil} does not operate by default on a particular {@link Scheduler}.</dd>
6932 * </dl>
6933 *
6934 * @param other
6935 * the second Observable that has to emit an item before the source Observable's elements begin
6936 * to be mirrored by the resulting Observable
6937 * @return an Observable that skips items from the source Observable until the second Observable emits an
6938 * item, then emits the remaining items
6939 * @see <a href="http://reactivex.io/documentation/operators/skipuntil.html">ReactiveX operators documentation: SkipUntil</a>
6940 */
6941 public final <U> Observable<T> skipUntil(Observable<U> other) {
6942 return lift(new OperatorSkipUntil<T, U>(other));
6943 }
6944
6945 /**
6946 * Returns an Observable that skips all items emitted by the source Observable as long as a specified
6947 * condition holds true, but emits all further source items as soon as the condition becomes false.
6948 * <p>
6949 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipWhile.png" alt="">
6950 * <dl>
6951 * <dt><b>Scheduler:</b></dt>
6952 * <dd>{@code skipWhile} does not operate by default on a particular {@link Scheduler}.</dd>
6953 * </dl>
6954 *
6955 * @param predicate
6956 * a function to test each item emitted from the source Observable
6957 * @return an Observable that begins emitting items emitted by the source Observable when the specified
6958 * predicate becomes false
6959 * @see <a href="http://reactivex.io/documentation/operators/skipwhile.html">ReactiveX operators documentation: SkipWhile</a>
6960 */
6961 public final Observable<T> skipWhile(Func1<? super T, Boolean> predicate) {
6962 return lift(new OperatorSkipWhile<T>(OperatorSkipWhile.toPredicate2(predicate)));
6963 }
6964
6965 /**
6966 * Returns an Observable that emits the items in a specified {@link Observable} before it begins to emit
6967 * items emitted by the source Observable.
6968 * <p>
6969 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.o.png" alt="">
6970 * <dl>
6971 * <dt><b>Scheduler:</b></dt>
6972 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
6973 * </dl>
6974 *
6975 * @param values
6976 * an Observable that contains the items you want the modified Observable to emit first
6977 * @return an Observable that emits the items in the specified {@link Observable} and then emits the items
6978 * emitted by the source Observable
6979 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
6980 */
6981 public final Observable<T> startWith(Observable<T> values) {
6982 return concat(values, this);
6983 }
6984
6985 /**
6986 * Returns an Observable that emits the items in a specified {@link Iterable} before it begins to emit items
6987 * emitted by the source Observable.
6988 * <p>
6989 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
6990 * <dl>
6991 * <dt><b>Scheduler:</b></dt>
6992 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
6993 * </dl>
6994 *
6995 * @param values
6996 * an Iterable that contains the items you want the modified Observable to emit first
6997 * @return an Observable that emits the items in the specified {@link Iterable} and then emits the items
6998 * emitted by the source Observable
6999 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7000 */
7001 public final Observable<T> startWith(Iterable<T> values) {
7002 return concat(Observable.<T> from(values), this);
7003 }
7004
7005 /**
7006 * Returns an Observable that emits a specified item before it begins to emit items emitted by the source
7007 * Observable.
7008 * <p>
7009 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
7010 * <dl>
7011 * <dt><b>Scheduler:</b></dt>
7012 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
7013 * </dl>
7014 *
7015 * @param t1
7016 * the item to emit
7017 * @return an Observable that emits the specified item before it begins to emit items emitted by the source
7018 * Observable
7019 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7020 */
7021 public final Observable<T> startWith(T t1) {
7022 return concat(just(t1), this);
7023 }
7024
7025 /**
7026 * Returns an Observable that emits the specified items before it begins to emit items emitted by the source
7027 * Observable.
7028 * <p>
7029 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
7030 * <dl>
7031 * <dt><b>Scheduler:</b></dt>
7032 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
7033 * </dl>
7034 *
7035 * @param t1
7036 * the first item to emit
7037 * @param t2
7038 * the second item to emit
7039 * @return an Observable that emits the specified items before it begins to emit items emitted by the source
7040 * Observable
7041 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7042 */
7043 public final Observable<T> startWith(T t1, T t2) {
7044 return concat(just(t1, t2), this);
7045 }
7046
7047 /**
7048 * Returns an Observable that emits the specified items before it begins to emit items emitted by the source
7049 * Observable.
7050 * <p>
7051 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
7052 * <dl>
7053 * <dt><b>Scheduler:</b></dt>
7054 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
7055 * </dl>
7056 *
7057 * @param t1
7058 * the first item to emit
7059 * @param t2
7060 * the second item to emit
7061 * @param t3
7062 * the third item to emit
7063 * @return an Observable that emits the specified items before it begins to emit items emitted by the source
7064 * Observable
7065 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7066 */
7067 public final Observable<T> startWith(T t1, T t2, T t3) {
7068 return concat(just(t1, t2, t3), this);
7069 }
7070
7071 /**
7072 * Returns an Observable that emits the specified items before it begins to emit items emitted by the source
7073 * Observable.
7074 * <p>
7075 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
7076 * <dl>
7077 * <dt><b>Scheduler:</b></dt>
7078 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
7079 * </dl>
7080 *
7081 * @param t1
7082 * the first item to emit
7083 * @param t2
7084 * the second item to emit
7085 * @param t3
7086 * the third item to emit
7087 * @param t4
7088 * the fourth item to emit
7089 * @return an Observable that emits the specified items before it begins to emit items emitted by the source
7090 * Observable
7091 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7092 */
7093 public final Observable<T> startWith(T t1, T t2, T t3, T t4) {
7094 return concat(just(t1, t2, t3, t4), this);
7095 }
7096
7097 /**
7098 * Returns an Observable that emits the specified items before it begins to emit items emitted by the source
7099 * Observable.
7100 * <p>
7101 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
7102 * <dl>
7103 * <dt><b>Scheduler:</b></dt>
7104 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
7105 * </dl>
7106 *
7107 * @param t1
7108 * the first item to emit
7109 * @param t2
7110 * the second item to emit
7111 * @param t3
7112 * the third item to emit
7113 * @param t4
7114 * the fourth item to emit
7115 * @param t5
7116 * the fifth item to emit
7117 * @return an Observable that emits the specified items before it begins to emit items emitted by the source
7118 * Observable
7119 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7120 */
7121 public final Observable<T> startWith(T t1, T t2, T t3, T t4, T t5) {
7122 return concat(just(t1, t2, t3, t4, t5), this);
7123 }
7124
7125 /**
7126 * Returns an Observable that emits the specified items before it begins to emit items emitted by the source
7127 * Observable.
7128 * <p>
7129 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
7130 * <dl>
7131 * <dt><b>Scheduler:</b></dt>
7132 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
7133 * </dl>
7134 *
7135 * @param t1
7136 * the first item to emit
7137 * @param t2
7138 * the second item to emit
7139 * @param t3
7140 * the third item to emit
7141 * @param t4
7142 * the fourth item to emit
7143 * @param t5
7144 * the fifth item to emit
7145 * @param t6
7146 * the sixth item to emit
7147 * @return an Observable that emits the specified items before it begins to emit items emitted
7148 * by the source Observable
7149 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7150 */
7151 public final Observable<T> startWith(T t1, T t2, T t3, T t4, T t5, T t6) {
7152 return concat(just(t1, t2, t3, t4, t5, t6), this);
7153 }
7154
7155 /**
7156 * Returns an Observable that emits the specified items before it begins to emit items emitted by the source
7157 * Observable.
7158 * <p>
7159 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
7160 * <dl>
7161 * <dt><b>Scheduler:</b></dt>
7162 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
7163 * </dl>
7164 *
7165 * @param t1
7166 * the first item to emit
7167 * @param t2
7168 * the second item to emit
7169 * @param t3
7170 * the third item to emit
7171 * @param t4
7172 * the fourth item to emit
7173 * @param t5
7174 * the fifth item to emit
7175 * @param t6
7176 * the sixth item to emit
7177 * @param t7
7178 * the seventh item to emit
7179 * @return an Observable that emits the specified items before it begins to emit items emitted by the source
7180 * Observable
7181 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7182 */
7183 public final Observable<T> startWith(T t1, T t2, T t3, T t4, T t5, T t6, T t7) {
7184 return concat(just(t1, t2, t3, t4, t5, t6, t7), this);
7185 }
7186
7187 /**
7188 * Returns an Observable that emits the specified items before it begins to emit items emitted by the source
7189 * Observable.
7190 * <p>
7191 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
7192 * <dl>
7193 * <dt><b>Scheduler:</b></dt>
7194 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
7195 * </dl>
7196 *
7197 * @param t1
7198 * the first item to emit
7199 * @param t2
7200 * the second item to emit
7201 * @param t3
7202 * the third item to emit
7203 * @param t4
7204 * the fourth item to emit
7205 * @param t5
7206 * the fifth item to emit
7207 * @param t6
7208 * the sixth item to emit
7209 * @param t7
7210 * the seventh item to emit
7211 * @param t8
7212 * the eighth item to emit
7213 * @return an Observable that emits the specified items before it begins to emit items emitted by the source
7214 * Observable
7215 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7216 */
7217 public final Observable<T> startWith(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8) {
7218 return concat(just(t1, t2, t3, t4, t5, t6, t7, t8), this);
7219 }
7220
7221 /**
7222 * Returns an Observable that emits the specified items before it begins to emit items emitted by the source
7223 * Observable.
7224 * <p>
7225 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.png" alt="">
7226 * <dl>
7227 * <dt><b>Scheduler:</b></dt>
7228 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
7229 * </dl>
7230 *
7231 * @param t1
7232 * the first item to emit
7233 * @param t2
7234 * the second item to emit
7235 * @param t3
7236 * the third item to emit
7237 * @param t4
7238 * the fourth item to emit
7239 * @param t5
7240 * the fifth item to emit
7241 * @param t6
7242 * the sixth item to emit
7243 * @param t7
7244 * the seventh item to emit
7245 * @param t8
7246 * the eighth item to emit
7247 * @param t9
7248 * the ninth item to emit
7249 * @return an Observable that emits the specified items before it begins to emit items emitted by the source
7250 * Observable
7251 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
7252 */
7253 public final Observable<T> startWith(T t1, T t2, T t3, T t4, T t5, T t6, T t7, T t8, T t9) {
7254 return concat(just(t1, t2, t3, t4, t5, t6, t7, t8, t9), this);
7255 }
7256
7257 /**
7258 * Subscribes to an Observable but ignore its emissions and notifications.
7259 * <dl>
7260 * <dt><b>Scheduler:</b></dt>
7261 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
7262 * </dl>
7263 *
7264 * @return a {@link Subscription} reference with which the {@link Observer} can stop receiving items before
7265 * the Observable has finished sending them
7266 * @throws OnErrorNotImplementedException
7267 * if the Observable tries to call {@code onError}
7268 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
7269 */
7270 public final Subscription subscribe() {
7271 return subscribe(new Subscriber<T>() {
7272
7273 @Override
7274 public final void onCompleted() {
7275 // do nothing
7276 }
7277
7278 @Override
7279 public final void onError(Throwable e) {
7280 throw new OnErrorNotImplementedException(e);
7281 }
7282
7283 @Override
7284 public final void onNext(T args) {
7285 // do nothing
7286 }
7287
7288 });
7289 }
7290
7291 /**
7292 * Subscribes to an Observable and provides a callback to handle the items it emits.
7293 * <dl>
7294 * <dt><b>Scheduler:</b></dt>
7295 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
7296 * </dl>
7297 *
7298 * @param onNext
7299 * the {@code Action1<T>} you have designed to accept emissions from the Observable
7300 * @return a {@link Subscription} reference with which the {@link Observer} can stop receiving items before
7301 * the Observable has finished sending them
7302 * @throws IllegalArgumentException
7303 * if {@code onNext} is null
7304 * @throws OnErrorNotImplementedException
7305 * if the Observable tries to call {@code onError}
7306 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
7307 */
7308 public final Subscription subscribe(final Action1<? super T> onNext) {
7309 if (onNext == null) {
7310 throw new IllegalArgumentException("onNext can not be null");
7311 }
7312
7313 return subscribe(new Subscriber<T>() {
7314
7315 @Override
7316 public final void onCompleted() {
7317 // do nothing
7318 }
7319
7320 @Override
7321 public final void onError(Throwable e) {
7322 throw new OnErrorNotImplementedException(e);
7323 }
7324
7325 @Override
7326 public final void onNext(T args) {
7327 onNext.call(args);
7328 }
7329
7330 });
7331 }
7332
7333 /**
7334 * Subscribes to an Observable and provides callbacks to handle the items it emits and any error
7335 * notification it issues.
7336 * <dl>
7337 * <dt><b>Scheduler:</b></dt>
7338 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
7339 * </dl>
7340 *
7341 * @param onNext
7342 * the {@code Action1<T>} you have designed to accept emissions from the Observable
7343 * @param onError
7344 * the {@code Action1<Throwable>} you have designed to accept any error notification from the
7345 * Observable
7346 * @return a {@link Subscription} reference with which the {@link Observer} can stop receiving items before
7347 * the Observable has finished sending them
7348 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
7349 * @throws IllegalArgumentException
7350 * if {@code onNext} is null, or
7351 * if {@code onError} is null
7352 */
7353 public final Subscription subscribe(final Action1<? super T> onNext, final Action1<Throwable> onError) {
7354 if (onNext == null) {
7355 throw new IllegalArgumentException("onNext can not be null");
7356 }
7357 if (onError == null) {
7358 throw new IllegalArgumentException("onError can not be null");
7359 }
7360
7361 return subscribe(new Subscriber<T>() {
7362
7363 @Override
7364 public final void onCompleted() {
7365 // do nothing
7366 }
7367
7368 @Override
7369 public final void onError(Throwable e) {
7370 onError.call(e);
7371 }
7372
7373 @Override
7374 public final void onNext(T args) {
7375 onNext.call(args);
7376 }
7377
7378 });
7379 }
7380
7381 /**
7382 * Subscribes to an Observable and provides callbacks to handle the items it emits and any error or
7383 * completion notification it issues.
7384 * <dl>
7385 * <dt><b>Scheduler:</b></dt>
7386 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
7387 * </dl>
7388 *
7389 * @param onNext
7390 * the {@code Action1<T>} you have designed to accept emissions from the Observable
7391 * @param onError
7392 * the {@code Action1<Throwable>} you have designed to accept any error notification from the
7393 * Observable
7394 * @param onComplete
7395 * the {@code Action0} you have designed to accept a completion notification from the
7396 * Observable
7397 * @return a {@link Subscription} reference with which the {@link Observer} can stop receiving items before
7398 * the Observable has finished sending them
7399 * @throws IllegalArgumentException
7400 * if {@code onNext} is null, or
7401 * if {@code onError} is null, or
7402 * if {@code onComplete} is null
7403 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
7404 */
7405 public final Subscription subscribe(final Action1<? super T> onNext, final Action1<Throwable> onError, final Action0 onComplete) {
7406 if (onNext == null) {
7407 throw new IllegalArgumentException("onNext can not be null");
7408 }
7409 if (onError == null) {
7410 throw new IllegalArgumentException("onError can not be null");
7411 }
7412 if (onComplete == null) {
7413 throw new IllegalArgumentException("onComplete can not be null");
7414 }
7415
7416 return subscribe(new Subscriber<T>() {
7417
7418 @Override
7419 public final void onCompleted() {
7420 onComplete.call();
7421 }
7422
7423 @Override
7424 public final void onError(Throwable e) {
7425 onError.call(e);
7426 }
7427
7428 @Override
7429 public final void onNext(T args) {
7430 onNext.call(args);
7431 }
7432
7433 });
7434 }
7435
7436 /**
7437 * Subscribes to an Observable and provides an Observer that implements functions to handle the items the
7438 * Observable emits and any error or completion notification it issues.
7439 * <dl>
7440 * <dt><b>Scheduler:</b></dt>
7441 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
7442 * </dl>
7443 *
7444 * @param observer
7445 * the Observer that will handle emissions and notifications from the Observable
7446 * @return a {@link Subscription} reference with which the {@link Observer} can stop receiving items before
7447 * the Observable has completed
7448 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
7449 */
7450 public final Subscription subscribe(final Observer<? super T> observer) {
7451 if (observer instanceof Subscriber) {
7452 return subscribe((Subscriber<? super T>)observer);
7453 }
7454 return subscribe(new Subscriber<T>() {
7455
7456 @Override
7457 public void onCompleted() {
7458 observer.onCompleted();
7459 }
7460
7461 @Override
7462 public void onError(Throwable e) {
7463 observer.onError(e);
7464 }
7465
7466 @Override
7467 public void onNext(T t) {
7468 observer.onNext(t);
7469 }
7470
7471 });
7472 }
7473
7474 /**
7475 * Subscribes to an Observable and invokes {@link OnSubscribe} function without any contract protection,
7476 * error handling, unsubscribe, or execution hooks.
7477 * <p>
7478 * Use this only for implementing an {@link Operator} that requires nested subscriptions. For other
7479 * purposes, use {@link #subscribe(Subscriber)} which ensures the Rx contract and other functionality.
7480 * <dl>
7481 * <dt><b>Scheduler:</b></dt>
7482 * <dd>{@code unsafeSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
7483 * </dl>
7484 *
7485 * @param subscriber
7486 * the Subscriber that will handle emissions and notifications from the Observable
7487 * @return a {@link Subscription} reference with which the {@link Subscriber} can stop receiving items
7488 * before the Observable has completed
7489 */
7490 public final Subscription unsafeSubscribe(Subscriber<? super T> subscriber) {
7491 try {
7492 // new Subscriber so onStart it
7493 subscriber.onStart();
7494 // allow the hook to intercept and/or decorate
7495 hook.onSubscribeStart(this, onSubscribe).call(subscriber);
7496 return hook.onSubscribeReturn(subscriber);
7497 } catch (Throwable e) {
7498 // special handling for certain Throwable/Error/Exception types
7499 Exceptions.throwIfFatal(e);
7500 // if an unhandled error occurs executing the onSubscribe we will propagate it
7501 try {
7502 subscriber.onError(hook.onSubscribeError(e));
7503 } catch (OnErrorNotImplementedException e2) {
7504 // special handling when onError is not implemented ... we just rethrow
7505 throw e2;
7506 } catch (Throwable e2) {
7507 // if this happens it means the onError itself failed (perhaps an invalid function implementation)
7508 // so we are unable to propagate the error correctly and will just throw
7509 RuntimeException r = new RuntimeException("Error occurred attempting to subscribe [" + e.getMessage() + "] and then again while trying to pass to onError.", e2);
7510 // TODO could the hook be the cause of the error in the on error handling.
7511 hook.onSubscribeError(r);
7512 // TODO why aren't we throwing the hook's return value.
7513 throw r;
7514 }
7515 return Subscriptions.unsubscribed();
7516 }
7517 }
7518
7519 /**
7520 * Subscribes to an Observable and provides a Subscriber that implements functions to handle the items the
7521 * Observable emits and any error or completion notification it issues.
7522 * <p>
7523 * A typical implementation of {@code subscribe} does the following:
7524 * <ol>
7525 * <li>It stores a reference to the Subscriber in a collection object, such as a {@code List<T>} object.</li>
7526 * <li>It returns a reference to the {@link Subscription} interface. This enables Subscribers to
7527 * unsubscribe, that is, to stop receiving items and notifications before the Observable completes, which
7528 * also invokes the Subscriber's {@link Subscriber#onCompleted onCompleted} method.</li>
7529 * </ol><p>
7530 * An {@code Observable<T>} instance is responsible for accepting all subscriptions and notifying all
7531 * Subscribers. Unless the documentation for a particular {@code Observable<T>} implementation indicates
7532 * otherwise, Subscriber should make no assumptions about the order in which multiple Subscribers will
7533 * receive their notifications.
7534 * <p>
7535 * For more information see the
7536 * <a href="http://reactivex.io/documentation/observable.html">ReactiveX documentation</a>.
7537 * <dl>
7538 * <dt><b>Scheduler:</b></dt>
7539 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
7540 * </dl>
7541 *
7542 * @param subscriber
7543 * the {@link Subscriber} that will handle emissions and notifications from the Observable
7544 * @return a {@link Subscription} reference with which Subscribers that are {@link Observer}s can
7545 * unsubscribe from the Observable
7546 * @throws IllegalStateException
7547 * if {@code subscribe} is unable to obtain an {@code OnSubscribe<>} function
7548 * @throws IllegalArgumentException
7549 * if the {@link Subscriber} provided as the argument to {@code subscribe} is {@code null}
7550 * @throws OnErrorNotImplementedException
7551 * if the {@link Subscriber}'s {@code onError} method is null
7552 * @throws RuntimeException
7553 * if the {@link Subscriber}'s {@code onError} method itself threw a {@code Throwable}
7554 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
7555 */
7556 public final Subscription subscribe(Subscriber<? super T> subscriber) {
7557 // validate and proceed
7558 if (subscriber == null) {
7559 throw new IllegalArgumentException("observer can not be null");
7560 }
7561 if (onSubscribe == null) {
7562 throw new IllegalStateException("onSubscribe function can not be null.");
7563 /*
7564 * the subscribe function can also be overridden but generally that's not the appropriate approach
7565 * so I won't mention that in the exception
7566 */
7567 }
7568
7569 // new Subscriber so onStart it
7570 subscriber.onStart();
7571
7572 /*
7573 * See https://github.com/ReactiveX/RxJava/issues/216 for discussion on "Guideline 6.4: Protect calls
7574 * to user code from within an Observer"
7575 */
7576 // if not already wrapped
7577 if (!(subscriber instanceof SafeSubscriber)) {
7578 // assign to `observer` so we return the protected version
7579 subscriber = new SafeSubscriber<T>(subscriber);
7580 }
7581
7582 // The code below is exactly the same an unsafeSubscribe but not used because it would add a sigificent depth to alreay huge call stacks.
7583 try {
7584 // allow the hook to intercept and/or decorate
7585 hook.onSubscribeStart(this, onSubscribe).call(subscriber);
7586 return hook.onSubscribeReturn(subscriber);
7587 } catch (Throwable e) {
7588 // special handling for certain Throwable/Error/Exception types
7589 Exceptions.throwIfFatal(e);
7590 // if an unhandled error occurs executing the onSubscribe we will propagate it
7591 try {
7592 subscriber.onError(hook.onSubscribeError(e));
7593 } catch (OnErrorNotImplementedException e2) {
7594 // special handling when onError is not implemented ... we just rethrow
7595 throw e2;
7596 } catch (Throwable e2) {
7597 // if this happens it means the onError itself failed (perhaps an invalid function implementation)
7598 // so we are unable to propagate the error correctly and will just throw
7599 RuntimeException r = new RuntimeException("Error occurred attempting to subscribe [" + e.getMessage() + "] and then again while trying to pass to onError.", e2);
7600 // TODO could the hook be the cause of the error in the on error handling.
7601 hook.onSubscribeError(r);
7602 // TODO why aren't we throwing the hook's return value.
7603 throw r;
7604 }
7605 return Subscriptions.unsubscribed();
7606 }
7607 }
7608
7609 /**
7610 * Asynchronously subscribes Observers to this Observable on the specified {@link Scheduler}.
7611 * <p>
7612 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/subscribeOn.png" alt="">
7613 * <dl>
7614 * <dt><b>Scheduler:</b></dt>
7615 * <dd>you specify which {@link Scheduler} this operator will use</dd>
7616 * </dl>
7617 *
7618 * @param scheduler
7619 * the {@link Scheduler} to perform subscription actions on
7620 * @return the source Observable modified so that its subscriptions happen on the
7621 * specified {@link Scheduler}
7622 * @see <a href="http://reactivex.io/documentation/operators/subscribeon.html">ReactiveX operators documentation: SubscribeOn</a>
7623 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
7624 * @see #observeOn
7625 */
7626 public final Observable<T> subscribeOn(Scheduler scheduler) {
7627 if (this instanceof ScalarSynchronousObservable) {
7628 return ((ScalarSynchronousObservable<T>)this).scalarScheduleOn(scheduler);
7629 }
7630 return nest().lift(new OperatorSubscribeOn<T>(scheduler));
7631 }
7632
7633 /**
7634 * Returns a new Observable by applying a function that you supply to each item emitted by the source
7635 * Observable that returns an Observable, and then emitting the items emitted by the most recently emitted
7636 * of these Observables.
7637 * <p>
7638 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.png" alt="">
7639 * <dl>
7640 * <dt><b>Scheduler:</b></dt>
7641 * <dd>{@code switchMap} does not operate by default on a particular {@link Scheduler}.</dd>
7642 * </dl>
7643 *
7644 * @param func
7645 * a function that, when applied to an item emitted by the source Observable, returns an
7646 * Observable
7647 * @return an Observable that emits the items emitted by the Observable returned from applying {@code func} to the most recently emitted item emitted by the source Observable
7648 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
7649 */
7650 public final <R> Observable<R> switchMap(Func1<? super T, ? extends Observable<? extends R>> func) {
7651 return switchOnNext(map(func));
7652 }
7653
7654 /**
7655 * Returns an Observable that emits only the first {@code num} items emitted by the source Observable.
7656 * <p>
7657 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.png" alt="">
7658 * <p>
7659 * This method returns an Observable that will invoke a subscribing {@link Observer}'s
7660 * {@link Observer#onNext onNext} function a maximum of {@code num} times before invoking
7661 * {@link Observer#onCompleted onCompleted}.
7662 * <dl>
7663 * <dt><b>Scheduler:</b></dt>
7664 * <dd>This version of {@code take} does not operate by default on a particular {@link Scheduler}.</dd>
7665 * </dl>
7666 *
7667 * @param num
7668 * the maximum number of items to emit
7669 * @return an Observable that emits only the first {@code num} items emitted by the source Observable, or
7670 * all of the items from the source Observable if that Observable emits fewer than {@code num} items
7671 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
7672 */
7673 public final Observable<T> take(final int num) {
7674 return lift(new OperatorTake<T>(num));
7675 }
7676
7677 /**
7678 * Returns an Observable that emits those items emitted by source Observable before a specified time runs
7679 * out.
7680 * <p>
7681 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.t.png" alt="">
7682 * <dl>
7683 * <dt><b>Scheduler:</b></dt>
7684 * <dd>This version of {@code take} operates by default on the {@code computation} {@link Scheduler}.</dd>
7685 * </dl>
7686 *
7687 * @param time
7688 * the length of the time window
7689 * @param unit
7690 * the time unit of {@code time}
7691 * @return an Observable that emits those items emitted by the source Observable before the time runs out
7692 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
7693 */
7694 public final Observable<T> take(long time, TimeUnit unit) {
7695 return take(time, unit, Schedulers.computation());
7696 }
7697
7698 /**
7699 * Returns an Observable that emits those items emitted by source Observable before a specified time (on a
7700 * specified Scheduler) runs out.
7701 * <p>
7702 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.ts.png" alt="">
7703 * <dl>
7704 * <dt><b>Scheduler:</b></dt>
7705 * <dd>you specify which {@link Scheduler} this operator will use</dd>
7706 * </dl>
7707 *
7708 * @param time
7709 * the length of the time window
7710 * @param unit
7711 * the time unit of {@code time}
7712 * @param scheduler
7713 * the Scheduler used for time source
7714 * @return an Observable that emits those items emitted by the source Observable before the time runs out,
7715 * according to the specified Scheduler
7716 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
7717 */
7718 public final Observable<T> take(long time, TimeUnit unit, Scheduler scheduler) {
7719 return lift(new OperatorTakeTimed<T>(time, unit, scheduler));
7720 }
7721
7722 /**
7723 * Returns an Observable that emits only the very first item emitted by the source Observable that satisfies
7724 * a specified condition.
7725 * <p>
7726 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeFirstN.png" alt="">
7727 * <dl>
7728 * <dt><b>Scheduler:</b></dt>
7729 * <dd>{@code takeFirst} does not operate by default on a particular {@link Scheduler}.</dd>
7730 * </dl>
7731 *
7732 * @param predicate
7733 * the condition any item emitted by the source Observable has to satisfy
7734 * @return an Observable that emits only the very first item emitted by the source Observable that satisfies
7735 * the given condition, or that completes without emitting anything if the source Observable
7736 * completes without emitting a single condition-satisfying item
7737 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
7738 */
7739 public final Observable<T> takeFirst(Func1<? super T, Boolean> predicate) {
7740 return filter(predicate).take(1);
7741 }
7742
7743 /**
7744 * Returns an Observable that emits only the last {@code count} items emitted by the source Observable.
7745 * <p>
7746 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.n.png" alt="">
7747 * <dl>
7748 * <dt><b>Scheduler:</b></dt>
7749 * <dd>This version of {@code takeLast} does not operate by default on a particular {@link Scheduler}.</dd>
7750 * </dl>
7751 *
7752 * @param count
7753 * the number of items to emit from the end of the sequence of items emitted by the source
7754 * Observable
7755 * @return an Observable that emits only the last {@code count} items emitted by the source Observable
7756 * @throws IndexOutOfBoundsException
7757 * if {@code count} is less than zero
7758 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7759 */
7760 public final Observable<T> takeLast(final int count) {
7761 return lift(new OperatorTakeLast<T>(count));
7762 }
7763
7764 /**
7765 * Returns an Observable that emits at most a specified number of items from the source Observable that were
7766 * emitted in a specified window of time before the Observable completed.
7767 * <p>
7768 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.tn.png" alt="">
7769 * <dl>
7770 * <dt><b>Scheduler:</b></dt>
7771 * <dd>This version of {@code takeLast} operates by default on the {@code computation} {@link Scheduler}.</dd>
7772 * </dl>
7773 *
7774 * @param count
7775 * the maximum number of items to emit
7776 * @param time
7777 * the length of the time window
7778 * @param unit
7779 * the time unit of {@code time}
7780 * @return an Observable that emits at most {@code count} items from the source Observable that were emitted
7781 * in a specified window of time before the Observable completed
7782 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7783 */
7784 public final Observable<T> takeLast(int count, long time, TimeUnit unit) {
7785 return takeLast(count, time, unit, Schedulers.computation());
7786 }
7787
7788 /**
7789 * Returns an Observable that emits at most a specified number of items from the source Observable that were
7790 * emitted in a specified window of time before the Observable completed, where the timing information is
7791 * provided by a given Scheduler.
7792 * <p>
7793 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.tns.png" alt="">
7794 * <dl>
7795 * <dt><b>Scheduler:</b></dt>
7796 * <dd>you specify which {@link Scheduler} this operator will use</dd>
7797 * </dl>
7798 *
7799 * @param count
7800 * the maximum number of items to emit
7801 * @param time
7802 * the length of the time window
7803 * @param unit
7804 * the time unit of {@code time}
7805 * @param scheduler
7806 * the {@link Scheduler} that provides the timestamps for the observed items
7807 * @return an Observable that emits at most {@code count} items from the source Observable that were emitted
7808 * in a specified window of time before the Observable completed, where the timing information is
7809 * provided by the given {@code scheduler}
7810 * @throws IndexOutOfBoundsException
7811 * if {@code count} is less than zero
7812 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7813 */
7814 public final Observable<T> takeLast(int count, long time, TimeUnit unit, Scheduler scheduler) {
7815 return lift(new OperatorTakeLastTimed<T>(count, time, unit, scheduler));
7816 }
7817
7818 /**
7819 * Returns an Observable that emits the items from the source Observable that were emitted in a specified
7820 * window of time before the Observable completed.
7821 * <p>
7822 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.t.png" alt="">
7823 * <dl>
7824 * <dt><b>Scheduler:</b></dt>
7825 * <dd>This version of {@code takeLast} operates by default on the {@code computation} {@link Scheduler}.</dd>
7826 * </dl>
7827 *
7828 * @param time
7829 * the length of the time window
7830 * @param unit
7831 * the time unit of {@code time}
7832 * @return an Observable that emits the items from the source Observable that were emitted in the window of
7833 * time before the Observable completed specified by {@code time}
7834 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7835 */
7836 public final Observable<T> takeLast(long time, TimeUnit unit) {
7837 return takeLast(time, unit, Schedulers.computation());
7838 }
7839
7840 /**
7841 * Returns an Observable that emits the items from the source Observable that were emitted in a specified
7842 * window of time before the Observable completed, where the timing information is provided by a specified
7843 * Scheduler.
7844 * <p>
7845 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.ts.png" alt="">
7846 * <dl>
7847 * <dt><b>Scheduler:</b></dt>
7848 * <dd>you specify which {@link Scheduler} this operator will use</dd>
7849 * </dl>
7850 *
7851 * @param time
7852 * the length of the time window
7853 * @param unit
7854 * the time unit of {@code time}
7855 * @param scheduler
7856 * the Scheduler that provides the timestamps for the Observed items
7857 * @return an Observable that emits the items from the source Observable that were emitted in the window of
7858 * time before the Observable completed specified by {@code time}, where the timing information is
7859 * provided by {@code scheduler}
7860 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7861 */
7862 public final Observable<T> takeLast(long time, TimeUnit unit, Scheduler scheduler) {
7863 return lift(new OperatorTakeLastTimed<T>(time, unit, scheduler));
7864 }
7865
7866 /**
7867 * Returns an Observable that emits a single List containing the last {@code count} elements emitted by the
7868 * source Observable.
7869 * <p>
7870 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLastBuffer.png" alt="">
7871 * <dl>
7872 * <dt><b>Scheduler:</b></dt>
7873 * <dd>This version of {@code takeLastBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
7874 * </dl>
7875 *
7876 * @param count
7877 * the number of items to emit in the list
7878 * @return an Observable that emits a single list containing the last {@code count} elements emitted by the
7879 * source Observable
7880 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7881 */
7882 public final Observable<List<T>> takeLastBuffer(int count) {
7883 return takeLast(count).toList();
7884 }
7885
7886 /**
7887 * Returns an Observable that emits a single List containing at most {@code count} items from the source
7888 * Observable that were emitted during a specified window of time before the source Observable completed.
7889 * <p>
7890 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLastBuffer.tn.png" alt="">
7891 * <dl>
7892 * <dt><b>Scheduler:</b></dt>
7893 * <dd>This version of {@code takeLastBuffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
7894 * </dl>
7895 *
7896 * @param count
7897 * the maximum number of items to emit
7898 * @param time
7899 * the length of the time window
7900 * @param unit
7901 * the time unit of {@code time}
7902 * @return an Observable that emits a single List containing at most {@code count} items emitted by the
7903 * source Observable during the time window defined by {@code time} before the source Observable
7904 * completed
7905 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7906 */
7907 public final Observable<List<T>> takeLastBuffer(int count, long time, TimeUnit unit) {
7908 return takeLast(count, time, unit).toList();
7909 }
7910
7911 /**
7912 * Returns an Observable that emits a single List containing at most {@code count} items from the source
7913 * Observable that were emitted during a specified window of time (on a specified Scheduler) before the
7914 * source Observable completed.
7915 * <p>
7916 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLastBuffer.tns.png" alt="">
7917 * <dl>
7918 * <dt><b>Scheduler:</b></dt>
7919 * <dd>you specify which {@link Scheduler} this operator will use</dd>
7920 * </dl>
7921 *
7922 * @param count
7923 * the maximum number of items to emit
7924 * @param time
7925 * the length of the time window
7926 * @param unit
7927 * the time unit of {@code time}
7928 * @param scheduler
7929 * the Scheduler that provides the timestamps for the observed items
7930 * @return an Observable that emits a single List containing at most {@code count} items emitted by the
7931 * source Observable during the time window defined by {@code time} before the source Observable
7932 * completed
7933 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7934 */
7935 public final Observable<List<T>> takeLastBuffer(int count, long time, TimeUnit unit, Scheduler scheduler) {
7936 return takeLast(count, time, unit, scheduler).toList();
7937 }
7938
7939 /**
7940 * Returns an Observable that emits a single List containing those items from the source Observable that
7941 * were emitted during a specified window of time before the source Observable completed.
7942 * <p>
7943 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLastBuffer.t.png" alt="">
7944 * <dl>
7945 * <dt><b>Scheduler:</b></dt>
7946 * <dd>This version of {@code takeLastBuffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
7947 * </dl>
7948 *
7949 * @param time
7950 * the length of the time window
7951 * @param unit
7952 * the time unit of {@code time}
7953 * @return an Observable that emits a single List containing the items emitted by the source Observable
7954 * during the time window defined by {@code time} before the source Observable completed
7955 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7956 */
7957 public final Observable<List<T>> takeLastBuffer(long time, TimeUnit unit) {
7958 return takeLast(time, unit).toList();
7959 }
7960
7961 /**
7962 * Returns an Observable that emits a single List containing those items from the source Observable that
7963 * were emitted during a specified window of time before the source Observable completed, where the timing
7964 * information is provided by the given Scheduler.
7965 * <p>
7966 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLastBuffer.ts.png" alt="">
7967 * <dl>
7968 * <dt><b>Scheduler:</b></dt>
7969 * <dd>you specify which {@link Scheduler} this operator will use</dd>
7970 * </dl>
7971 *
7972 * @param time
7973 * the length of the time window
7974 * @param unit
7975 * the time unit of {@code time}
7976 * @param scheduler
7977 * the Scheduler that provides the timestamps for the observed items
7978 * @return an Observable that emits a single List containing the items emitted by the source Observable
7979 * during the time window defined by {@code time} before the source Observable completed, where the
7980 * timing information is provided by {@code scheduler}
7981 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
7982 */
7983 public final Observable<List<T>> takeLastBuffer(long time, TimeUnit unit, Scheduler scheduler) {
7984 return takeLast(time, unit, scheduler).toList();
7985 }
7986
7987 /**
7988 * Returns an Observable that emits the items emitted by the source Observable until a second Observable
7989 * emits an item.
7990 * <p>
7991 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeUntil.png" alt="">
7992 * <dl>
7993 * <dt><b>Scheduler:</b></dt>
7994 * <dd>{@code takeUntil} does not operate by default on a particular {@link Scheduler}.</dd>
7995 * </dl>
7996 *
7997 * @param other
7998 * the Observable whose first emitted item will cause {@code takeUntil} to stop emitting items
7999 * from the source Observable
8000 * @param <E>
8001 * the type of items emitted by {@code other}
8002 * @return an Observable that emits the items emitted by the source Observable until such time as {@code other} emits its first item
8003 * @see <a href="http://reactivex.io/documentation/operators/takeuntil.html">ReactiveX operators documentation: TakeUntil</a>
8004 */
8005 public final <E> Observable<T> takeUntil(Observable<? extends E> other) {
8006 return lift(new OperatorTakeUntil<T, E>(other));
8007 }
8008
8009 /**
8010 * Returns an Observable that emits items emitted by the source Observable so long as each item satisfied a
8011 * specified condition, and then completes as soon as this condition is not satisfied.
8012 * <p>
8013 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeWhile.png" alt="">
8014 * <dl>
8015 * <dt><b>Scheduler:</b></dt>
8016 * <dd>{@code takeWhile} does not operate by default on a particular {@link Scheduler}.</dd>
8017 * </dl>
8018 *
8019 * @param predicate
8020 * a function that evaluates an item emitted by the source Observable and returns a Boolean
8021 * @return an Observable that emits the items from the source Observable so long as each item satisfies the
8022 * condition defined by {@code predicate}, then completes
8023 * @see <a href="http://reactivex.io/documentation/operators/takewhile.html">ReactiveX operators documentation: TakeWhile</a>
8024 * @see Observable#takeUntil(Func1)
8025 */
8026 public final Observable<T> takeWhile(final Func1<? super T, Boolean> predicate) {
8027 return lift(new OperatorTakeWhile<T>(predicate));
8028 }
8029
8030 /**
8031 * Returns an Observable that emits items emitted by the source Observable, checks the specified predicate
8032 * for each item, and then completes if the condition is satisfied.
8033 * <p>
8034 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeUntil.p.png" alt="">
8035 * <p>
8036 * The difference between this operator and {@link #takeWhile(Func1)} is that here, the condition is
8037 * evaluated <em>after</em> the item is emitted.
8038 *
8039 * @warn "Scheduler" and "Backpressure Support" sections missing from javadocs
8040 * @param stopPredicate
8041 * a function that evaluates an item emitted by the source Observable and returns a Boolean
8042 * @return an Observable that first emits items emitted by the source Observable, checks the specified
8043 * condition after each item, and then completes if the condition is satisfied.
8044 * @see <a href="http://reactivex.io/documentation/operators/takeuntil.html">ReactiveX operators documentation: TakeUntil</a>
8045 * @see Observable#takeWhile(Func1)
8046 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
8047 */
8048 @Experimental
8049 public final Observable<T> takeUntil(final Func1<? super T, Boolean> stopPredicate) {
8050 return lift(new OperatorTakeUntilPredicate<T>(stopPredicate));
8051 }
8052
8053 /**
8054 * Returns an Observable that emits only the first item emitted by the source Observable during sequential
8055 * time windows of a specified duration.
8056 * <p>
8057 * This differs from {@link #throttleLast} in that this only tracks passage of time whereas
8058 * {@link #throttleLast} ticks at scheduled intervals.
8059 * <p>
8060 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleFirst.png" alt="">
8061 * <dl>
8062 * <dt><b>Backpressure Support:</b></dt>
8063 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8064 * <dt><b>Scheduler:</b></dt>
8065 * <dd>{@code throttleFirst} operates by default on the {@code computation} {@link Scheduler}.</dd>
8066 * </dl>
8067 *
8068 * @param windowDuration
8069 * time to wait before emitting another item after emitting the last item
8070 * @param unit
8071 * the unit of time of {@code windowDuration}
8072 * @return an Observable that performs the throttle operation
8073 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
8074 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
8075 */
8076 public final Observable<T> throttleFirst(long windowDuration, TimeUnit unit) {
8077 return throttleFirst(windowDuration, unit, Schedulers.computation());
8078 }
8079
8080 /**
8081 * Returns an Observable that emits only the first item emitted by the source Observable during sequential
8082 * time windows of a specified duration, where the windows are managed by a specified Scheduler.
8083 * <p>
8084 * This differs from {@link #throttleLast} in that this only tracks passage of time whereas
8085 * {@link #throttleLast} ticks at scheduled intervals.
8086 * <p>
8087 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleFirst.s.png" alt="">
8088 * <dl>
8089 * <dt><b>Backpressure Support:</b></dt>
8090 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8091 * <dt><b>Scheduler:</b></dt>
8092 * <dd>you specify which {@link Scheduler} this operator will use</dd>
8093 * </dl>
8094 *
8095 * @param skipDuration
8096 * time to wait before emitting another item after emitting the last item
8097 * @param unit
8098 * the unit of time of {@code skipDuration}
8099 * @param scheduler
8100 * the {@link Scheduler} to use internally to manage the timers that handle timeout for each
8101 * event
8102 * @return an Observable that performs the throttle operation
8103 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
8104 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
8105 */
8106 public final Observable<T> throttleFirst(long skipDuration, TimeUnit unit, Scheduler scheduler) {
8107 return lift(new OperatorThrottleFirst<T>(skipDuration, unit, scheduler));
8108 }
8109
8110 /**
8111 * Returns an Observable that emits only the last item emitted by the source Observable during sequential
8112 * time windows of a specified duration.
8113 * <p>
8114 * This differs from {@link #throttleFirst} in that this ticks along at a scheduled interval whereas
8115 * {@link #throttleFirst} does not tick, it just tracks passage of time.
8116 * <p>
8117 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLast.png" alt="">
8118 * <dl>
8119 * <dt><b>Backpressure Support:</b></dt>
8120 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8121 * <dt><b>Scheduler:</b></dt>
8122 * <dd>{@code throttleLast} operates by default on the {@code computation} {@link Scheduler}.</dd>
8123 * </dl>
8124 *
8125 * @param intervalDuration
8126 * duration of windows within which the last item emitted by the source Observable will be
8127 * emitted
8128 * @param unit
8129 * the unit of time of {@code intervalDuration}
8130 * @return an Observable that performs the throttle operation
8131 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
8132 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
8133 * @see #sample(long, TimeUnit)
8134 */
8135 public final Observable<T> throttleLast(long intervalDuration, TimeUnit unit) {
8136 return sample(intervalDuration, unit);
8137 }
8138
8139 /**
8140 * Returns an Observable that emits only the last item emitted by the source Observable during sequential
8141 * time windows of a specified duration, where the duration is governed by a specified Scheduler.
8142 * <p>
8143 * This differs from {@link #throttleFirst} in that this ticks along at a scheduled interval whereas
8144 * {@link #throttleFirst} does not tick, it just tracks passage of time.
8145 * <p>
8146 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLast.s.png" alt="">
8147 * <dl>
8148 * <dt><b>Backpressure Support:</b></dt>
8149 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8150 * <dt><b>Scheduler:</b></dt>
8151 * <dd>you specify which {@link Scheduler} this operator will use</dd>
8152 * </dl>
8153 *
8154 * @param intervalDuration
8155 * duration of windows within which the last item emitted by the source Observable will be
8156 * emitted
8157 * @param unit
8158 * the unit of time of {@code intervalDuration}
8159 * @param scheduler
8160 * the {@link Scheduler} to use internally to manage the timers that handle timeout for each
8161 * event
8162 * @return an Observable that performs the throttle operation
8163 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
8164 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
8165 * @see #sample(long, TimeUnit, Scheduler)
8166 */
8167 public final Observable<T> throttleLast(long intervalDuration, TimeUnit unit, Scheduler scheduler) {
8168 return sample(intervalDuration, unit, scheduler);
8169 }
8170
8171 /**
8172 * Returns an Observable that only emits those items emitted by the source Observable that are not followed
8173 * by another emitted item within a specified time window.
8174 * <p>
8175 * <em>Note:</em> If the source Observable keeps emitting items more frequently than the length of the time
8176 * window then no items will be emitted by the resulting Observable.
8177 * <p>
8178 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleWithTimeout.png" alt="">
8179 * <p>
8180 * Information on debounce vs throttle:
8181 * <p>
8182 * <ul>
8183 * <li><a href="http://drupalmotion.com/article/debounce-and-throttle-visual-explanation">Debounce and Throttle: visual explanation</a></li>
8184 * <li><a href="http://unscriptable.com/2009/03/20/debouncing-javascript-methods/">Debouncing: javascript methods</a></li>
8185 * <li><a href="http://www.illyriad.co.uk/blog/index.php/2011/09/javascript-dont-spam-your-server-debounce-and-throttle/">Javascript - don't spam your server: debounce and throttle</a></li>
8186 * </ul>
8187 * <dl>
8188 * <dt><b>Backpressure Support:</b></dt>
8189 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8190 * <dt><b>Scheduler:</b></dt>
8191 * <dd>{@code throttleWithTimeout} operates by default on the {@code computation} {@link Scheduler}.</dd>
8192 * </dl>
8193 *
8194 * @param timeout
8195 * the length of the window of time that must pass after the emission of an item from the source
8196 * Observable in which that Observable emits no items in order for the item to be emitted by the
8197 * resulting Observable
8198 * @param unit
8199 * the {@link TimeUnit} of {@code timeout}
8200 * @return an Observable that filters out items that are too quickly followed by newer items
8201 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
8202 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
8203 * @see #debounce(long, TimeUnit)
8204 */
8205 public final Observable<T> throttleWithTimeout(long timeout, TimeUnit unit) {
8206 return debounce(timeout, unit);
8207 }
8208
8209 /**
8210 * Returns an Observable that only emits those items emitted by the source Observable that are not followed
8211 * by another emitted item within a specified time window, where the time window is governed by a specified
8212 * Scheduler.
8213 * <p>
8214 * <em>Note:</em> If the source Observable keeps emitting items more frequently than the length of the time
8215 * window then no items will be emitted by the resulting Observable.
8216 * <p>
8217 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleWithTimeout.s.png" alt="">
8218 * <p>
8219 * Information on debounce vs throttle:
8220 * <p>
8221 * <ul>
8222 * <li><a href="http://drupalmotion.com/article/debounce-and-throttle-visual-explanation">Debounce and Throttle: visual explanation</a></li>
8223 * <li><a href="http://unscriptable.com/2009/03/20/debouncing-javascript-methods/">Debouncing: javascript methods</a></li>
8224 * <li><a href="http://www.illyriad.co.uk/blog/index.php/2011/09/javascript-dont-spam-your-server-debounce-and-throttle/">Javascript - don't spam your server: debounce and throttle</a></li>
8225 * </ul>
8226 * <dl>
8227 * <dt><b>Backpressure Support:</b></dt>
8228 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8229 * <dt><b>Scheduler:</b></dt>
8230 * <dd>you specify which {@link Scheduler} this operator will use</dd>
8231 * </dl>
8232 *
8233 * @param timeout
8234 * the length of the window of time that must pass after the emission of an item from the source
8235 * Observable in which that Observable emits no items in order for the item to be emitted by the
8236 * resulting Observable
8237 * @param unit
8238 * the {@link TimeUnit} of {@code timeout}
8239 * @param scheduler
8240 * the {@link Scheduler} to use internally to manage the timers that handle the timeout for each
8241 * item
8242 * @return an Observable that filters out items that are too quickly followed by newer items
8243 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
8244 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
8245 * @see #debounce(long, TimeUnit, Scheduler)
8246 */
8247 public final Observable<T> throttleWithTimeout(long timeout, TimeUnit unit, Scheduler scheduler) {
8248 return debounce(timeout, unit, scheduler);
8249 }
8250
8251 /**
8252 * Returns an Observable that emits records of the time interval between consecutive items emitted by the
8253 * source Observable.
8254 * <p>
8255 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.png" alt="">
8256 * <dl>
8257 * <dt><b>Scheduler:</b></dt>
8258 * <dd>{@code timeInterval} operates by default on the {@code immediate} {@link Scheduler}.</dd>
8259 * </dl>
8260 *
8261 * @return an Observable that emits time interval information items
8262 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
8263 */
8264 public final Observable<TimeInterval<T>> timeInterval() {
8265 return timeInterval(Schedulers.immediate());
8266 }
8267
8268 /**
8269 * Returns an Observable that emits records of the time interval between consecutive items emitted by the
8270 * source Observable, where this interval is computed on a specified Scheduler.
8271 * <p>
8272 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.s.png" alt="">
8273 * <dl>
8274 * <dt><b>Scheduler:</b></dt>
8275 * <dd>you specify which {@link Scheduler} this operator will use</dd>
8276 * </dl>
8277 *
8278 * @param scheduler
8279 * the {@link Scheduler} used to compute time intervals
8280 * @return an Observable that emits time interval information items
8281 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
8282 */
8283 public final Observable<TimeInterval<T>> timeInterval(Scheduler scheduler) {
8284 return lift(new OperatorTimeInterval<T>(scheduler));
8285 }
8286
8287 /**
8288 * Returns an Observable that mirrors the source Observable, but notifies observers of a
8289 * {@code TimeoutException} if either the first item emitted by the source Observable or any subsequent item
8290 * doesn't arrive within time windows defined by other Observables.
8291 * <p>
8292 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout5.png" alt="">
8293 * <dl>
8294 * <dt><b>Scheduler:</b></dt>
8295 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
8296 * </dl>
8297 *
8298 * @param <U>
8299 * the first timeout value type (ignored)
8300 * @param <V>
8301 * the subsequent timeout value type (ignored)
8302 * @param firstTimeoutSelector
8303 * a function that returns an Observable that determines the timeout window for the first source
8304 * item
8305 * @param timeoutSelector
8306 * a function that returns an Observable for each item emitted by the source Observable and that
8307 * determines the timeout window in which the subsequent source item must arrive in order to
8308 * continue the sequence
8309 * @return an Observable that mirrors the source Observable, but notifies observers of a
8310 * {@code TimeoutException} if either the first item or any subsequent item doesn't arrive within
8311 * the time windows specified by the timeout selectors
8312 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
8313 */
8314 public final <U, V> Observable<T> timeout(Func0<? extends Observable<U>> firstTimeoutSelector, Func1<? super T, ? extends Observable<V>> timeoutSelector) {
8315 return timeout(firstTimeoutSelector, timeoutSelector, null);
8316 }
8317
8318 /**
8319 * Returns an Observable that mirrors the source Observable, but switches to a fallback Observable if either
8320 * the first item emitted by the source Observable or any subsequent item doesn't arrive within time windows
8321 * defined by other Observables.
8322 * <p>
8323 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout6.png" alt="">
8324 * <dl>
8325 * <dt><b>Scheduler:</b></dt>
8326 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
8327 * </dl>
8328 *
8329 * @param <U>
8330 * the first timeout value type (ignored)
8331 * @param <V>
8332 * the subsequent timeout value type (ignored)
8333 * @param firstTimeoutSelector
8334 * a function that returns an Observable which determines the timeout window for the first source
8335 * item
8336 * @param timeoutSelector
8337 * a function that returns an Observable for each item emitted by the source Observable and that
8338 * determines the timeout window in which the subsequent source item must arrive in order to
8339 * continue the sequence
8340 * @param other
8341 * the fallback Observable to switch to if the source Observable times out
8342 * @return an Observable that mirrors the source Observable, but switches to the {@code other} Observable if
8343 * either the first item emitted by the source Observable or any subsequent item doesn't arrive
8344 * within time windows defined by the timeout selectors
8345 * @throws NullPointerException
8346 * if {@code timeoutSelector} is null
8347 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
8348 */
8349 public final <U, V> Observable<T> timeout(Func0<? extends Observable<U>> firstTimeoutSelector, Func1<? super T, ? extends Observable<V>> timeoutSelector, Observable<? extends T> other) {
8350 if (timeoutSelector == null) {
8351 throw new NullPointerException("timeoutSelector is null");
8352 }
8353 return lift(new OperatorTimeoutWithSelector<T, U, V>(firstTimeoutSelector, timeoutSelector, other));
8354 }
8355
8356 /**
8357 * Returns an Observable that mirrors the source Observable, but notifies observers of a
8358 * {@code TimeoutException} if an item emitted by the source Observable doesn't arrive within a window of
8359 * time after the emission of the previous item, where that period of time is measured by an Observable that
8360 * is a function of the previous item.
8361 * <p>
8362 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout3.png" alt="">
8363 * <p>
8364 * Note: The arrival of the first source item is never timed out.
8365 * <dl>
8366 * <dt><b>Scheduler:</b></dt>
8367 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
8368 * </dl>
8369 *
8370 * @param <V>
8371 * the timeout value type (ignored)
8372 * @param timeoutSelector
8373 * a function that returns an observable for each item emitted by the source
8374 * Observable and that determines the timeout window for the subsequent item
8375 * @return an Observable that mirrors the source Observable, but notifies observers of a
8376 * {@code TimeoutException} if an item emitted by the source Observable takes longer to arrive than
8377 * the time window defined by the selector for the previously emitted item
8378 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
8379 */
8380 public final <V> Observable<T> timeout(Func1<? super T, ? extends Observable<V>> timeoutSelector) {
8381 return timeout(null, timeoutSelector, null);
8382 }
8383
8384 /**
8385 * Returns an Observable that mirrors the source Observable, but that switches to a fallback Observable if
8386 * an item emitted by the source Observable doesn't arrive within a window of time after the emission of the
8387 * previous item, where that period of time is measured by an Observable that is a function of the previous
8388 * item.
8389 * <p>
8390 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout4.png" alt="">
8391 * <p>
8392 * Note: The arrival of the first source item is never timed out.
8393 * <dl>
8394 * <dt><b>Scheduler:</b></dt>
8395 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
8396 * </dl>
8397 *
8398 * @param <V>
8399 * the timeout value type (ignored)
8400 * @param timeoutSelector
8401 * a function that returns an Observable, for each item emitted by the source Observable, that
8402 * determines the timeout window for the subsequent item
8403 * @param other
8404 * the fallback Observable to switch to if the source Observable times out
8405 * @return an Observable that mirrors the source Observable, but switches to mirroring a fallback Observable
8406 * if an item emitted by the source Observable takes longer to arrive than the time window defined
8407 * by the selector for the previously emitted item
8408 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
8409 */
8410 public final <V> Observable<T> timeout(Func1<? super T, ? extends Observable<V>> timeoutSelector, Observable<? extends T> other) {
8411 return timeout(null, timeoutSelector, other);
8412 }
8413
8414 /**
8415 * Returns an Observable that mirrors the source Observable but applies a timeout policy for each emitted
8416 * item. If the next item isn't emitted within the specified timeout duration starting from its predecessor,
8417 * the resulting Observable terminates and notifies observers of a {@code TimeoutException}.
8418 * <p>
8419 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.1.png" alt="">
8420 * <dl>
8421 * <dt><b>Scheduler:</b></dt>
8422 * <dd>This version of {@code timeout} operates by default on the {@code computation} {@link Scheduler}.</dd>
8423 * </dl>
8424 *
8425 * @param timeout
8426 * maximum duration between emitted items before a timeout occurs
8427 * @param timeUnit
8428 * the unit of time that applies to the {@code timeout} argument.
8429 * @return the source Observable modified to notify observers of a {@code TimeoutException} in case of a
8430 * timeout
8431 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
8432 */
8433 public final Observable<T> timeout(long timeout, TimeUnit timeUnit) {
8434 return timeout(timeout, timeUnit, null, Schedulers.computation());
8435 }
8436
8437 /**
8438 * Returns an Observable that mirrors the source Observable but applies a timeout policy for each emitted
8439 * item. If the next item isn't emitted within the specified timeout duration starting from its predecessor,
8440 * the resulting Observable begins instead to mirror a fallback Observable.
8441 * <p>
8442 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.2.png" alt="">
8443 * <dl>
8444 * <dt><b>Scheduler:</b></dt>
8445 * <dd>This version of {@code timeout} operates by default on the {@code computation} {@link Scheduler}.</dd>
8446 * </dl>
8447 *
8448 * @param timeout
8449 * maximum duration between items before a timeout occurs
8450 * @param timeUnit
8451 * the unit of time that applies to the {@code timeout} argument
8452 * @param other
8453 * the fallback Observable to use in case of a timeout
8454 * @return the source Observable modified to switch to the fallback Observable in case of a timeout
8455 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
8456 */
8457 public final Observable<T> timeout(long timeout, TimeUnit timeUnit, Observable<? extends T> other) {
8458 return timeout(timeout, timeUnit, other, Schedulers.computation());
8459 }
8460
8461 /**
8462 * Returns an Observable that mirrors the source Observable but applies a timeout policy for each emitted
8463 * item using a specified Scheduler. If the next item isn't emitted within the specified timeout duration
8464 * starting from its predecessor, the resulting Observable begins instead to mirror a fallback Observable.
8465 * <p>
8466 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.2s.png" alt="">
8467 * <dl>
8468 * <dt><b>Scheduler:</b></dt>
8469 * <dd>you specify which {@link Scheduler} this operator will use</dd>
8470 * </dl>
8471 *
8472 * @param timeout
8473 * maximum duration between items before a timeout occurs
8474 * @param timeUnit
8475 * the unit of time that applies to the {@code timeout} argument
8476 * @param other
8477 * the Observable to use as the fallback in case of a timeout
8478 * @param scheduler
8479 * the {@link Scheduler} to run the timeout timers on
8480 * @return the source Observable modified so that it will switch to the fallback Observable in case of a
8481 * timeout
8482 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
8483 */
8484 public final Observable<T> timeout(long timeout, TimeUnit timeUnit, Observable<? extends T> other, Scheduler scheduler) {
8485 return lift(new OperatorTimeout<T>(timeout, timeUnit, other, scheduler));
8486 }
8487
8488 /**
8489 * Returns an Observable that mirrors the source Observable but applies a timeout policy for each emitted
8490 * item, where this policy is governed on a specified Scheduler. If the next item isn't emitted within the
8491 * specified timeout duration starting from its predecessor, the resulting Observable terminates and
8492 * notifies observers of a {@code TimeoutException}.
8493 * <p>
8494 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.1s.png" alt="">
8495 * <dl>
8496 * <dt><b>Scheduler:</b></dt>
8497 * <dd>you specify which {@link Scheduler} this operator will use</dd>
8498 * </dl>
8499 *
8500 * @param timeout
8501 * maximum duration between items before a timeout occurs
8502 * @param timeUnit
8503 * the unit of time that applies to the {@code timeout} argument
8504 * @param scheduler
8505 * the Scheduler to run the timeout timers on
8506 * @return the source Observable modified to notify observers of a {@code TimeoutException} in case of a
8507 * timeout
8508 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
8509 */
8510 public final Observable<T> timeout(long timeout, TimeUnit timeUnit, Scheduler scheduler) {
8511 return timeout(timeout, timeUnit, null, scheduler);
8512 }
8513
8514 /**
8515 * Returns an Observable that emits each item emitted by the source Observable, wrapped in a
8516 * {@link Timestamped} object.
8517 * <p>
8518 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.png" alt="">
8519 * <dl>
8520 * <dt><b>Scheduler:</b></dt>
8521 * <dd>{@code timestamp} operates by default on the {@code immediate} {@link Scheduler}.</dd>
8522 * </dl>
8523 *
8524 * @return an Observable that emits timestamped items from the source Observable
8525 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
8526 */
8527 public final Observable<Timestamped<T>> timestamp() {
8528 return timestamp(Schedulers.immediate());
8529 }
8530
8531 /**
8532 * Returns an Observable that emits each item emitted by the source Observable, wrapped in a
8533 * {@link Timestamped} object whose timestamps are provided by a specified Scheduler.
8534 * <p>
8535 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.s.png" alt="">
8536 * <dl>
8537 * <dt><b>Scheduler:</b></dt>
8538 * <dd>you specify which {@link Scheduler} this operator will use</dd>
8539 * </dl>
8540 *
8541 * @param scheduler
8542 * the {@link Scheduler} to use as a time source
8543 * @return an Observable that emits timestamped items from the source Observable with timestamps provided by
8544 * the {@code scheduler}
8545 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
8546 */
8547 public final Observable<Timestamped<T>> timestamp(Scheduler scheduler) {
8548 return lift(new OperatorTimestamp<T>(scheduler));
8549 }
8550
8551 /**
8552 * Converts an Observable into a {@link BlockingObservable} (an Observable with blocking operators).
8553 * <dl>
8554 * <dt><b>Scheduler:</b></dt>
8555 * <dd>{@code toBlocking} does not operate by default on a particular {@link Scheduler}.</dd>
8556 * </dl>
8557 *
8558 * @return a {@code BlockingObservable} version of this Observable
8559 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8560 */
8561 public final BlockingObservable<T> toBlocking() {
8562 return BlockingObservable.from(this);
8563 }
8564
8565 /**
8566 * Returns an Observable that emits a single item, a list composed of all the items emitted by the source
8567 * Observable.
8568 * <p>
8569 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toList.png" alt="">
8570 * <p>
8571 * Normally, an Observable that returns multiple items will do so by invoking its {@link Observer}'s
8572 * {@link Observer#onNext onNext} method for each such item. You can change this behavior, instructing the
8573 * Observable to compose a list of all of these items and then to invoke the Observer's {@code onNext}
8574 * function once, passing it the entire list, by calling the Observable's {@code toList} method prior to
8575 * calling its {@link #subscribe} method.
8576 * <p>
8577 * Be careful not to use this operator on Observables that emit infinite or very large numbers of items, as
8578 * you do not have the option to unsubscribe.
8579 * <dl>
8580 * <dt><b>Backpressure Support:</b></dt>
8581 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8582 * <dt><b>Scheduler:</b></dt>
8583 * <dd>{@code toList} does not operate by default on a particular {@link Scheduler}.</dd>
8584 * </dl>
8585 *
8586 * @return an Observable that emits a single item: a List containing all of the items emitted by the source
8587 * Observable
8588 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8589 */
8590 public final Observable<List<T>> toList() {
8591 return lift(OperatorToObservableList.<T>instance());
8592 }
8593
8594 /**
8595 * Returns an Observable that emits a single HashMap containing all items emitted by the source Observable,
8596 * mapped by the keys returned by a specified {@code keySelector} function.
8597 * <p>
8598 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMap.png" alt="">
8599 * <p>
8600 * If more than one source item maps to the same key, the HashMap will contain the latest of those items.
8601 * <dl>
8602 * <dt><b>Backpressure Support:</b></dt>
8603 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8604 * <dt><b>Scheduler:</b></dt>
8605 * <dd>{@code toMap} does not operate by default on a particular {@link Scheduler}.</dd>
8606 * </dl>
8607 *
8608 * @param keySelector
8609 * the function that extracts the key from a source item to be used in the HashMap
8610 * @return an Observable that emits a single item: a HashMap containing the mapped items from the source
8611 * Observable
8612 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8613 */
8614 public final <K> Observable<Map<K, T>> toMap(Func1<? super T, ? extends K> keySelector) {
8615 return lift(new OperatorToMap<T, K, T>(keySelector, UtilityFunctions.<T>identity()));
8616 }
8617
8618 /**
8619 * Returns an Observable that emits a single HashMap containing values corresponding to items emitted by the
8620 * source Observable, mapped by the keys returned by a specified {@code keySelector} function.
8621 * <p>
8622 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMap.png" alt="">
8623 * <p>
8624 * If more than one source item maps to the same key, the HashMap will contain a single entry that
8625 * corresponds to the latest of those items.
8626 * <dl>
8627 * <dt><b>Backpressure Support:</b></dt>
8628 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8629 * <dt><b>Scheduler:</b></dt>
8630 * <dd>{@code toMap} does not operate by default on a particular {@link Scheduler}.</dd>
8631 * </dl>
8632 *
8633 * @param keySelector
8634 * the function that extracts the key from a source item to be used in the HashMap
8635 * @param valueSelector
8636 * the function that extracts the value from a source item to be used in the HashMap
8637 * @return an Observable that emits a single item: a HashMap containing the mapped items from the source
8638 * Observable
8639 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8640 */
8641 public final <K, V> Observable<Map<K, V>> toMap(Func1<? super T, ? extends K> keySelector, Func1<? super T, ? extends V> valueSelector) {
8642 return lift(new OperatorToMap<T, K, V>(keySelector, valueSelector));
8643 }
8644
8645 /**
8646 * Returns an Observable that emits a single Map, returned by a specified {@code mapFactory} function, that
8647 * contains keys and values extracted from the items emitted by the source Observable.
8648 * <p>
8649 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMap.png" alt="">
8650 * <dl>
8651 * <dt><b>Backpressure Support:</b></dt>
8652 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8653 * <dt><b>Scheduler:</b></dt>
8654 * <dd>{@code toMap} does not operate by default on a particular {@link Scheduler}.</dd>
8655 * </dl>
8656 *
8657 * @param keySelector
8658 * the function that extracts the key from a source item to be used in the Map
8659 * @param valueSelector
8660 * the function that extracts the value from the source items to be used as value in the Map
8661 * @param mapFactory
8662 * the function that returns a Map instance to be used
8663 * @return an Observable that emits a single item: a Map that contains the mapped items emitted by the
8664 * source Observable
8665 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8666 */
8667 public final <K, V> Observable<Map<K, V>> toMap(Func1<? super T, ? extends K> keySelector, Func1<? super T, ? extends V> valueSelector, Func0<? extends Map<K, V>> mapFactory) {
8668 return lift(new OperatorToMap<T, K, V>(keySelector, valueSelector, mapFactory));
8669 }
8670
8671 /**
8672 * Returns an Observable that emits a single HashMap that contains an ArrayList of items emitted by the
8673 * source Observable keyed by a specified {@code keySelector} function.
8674 * <p>
8675 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.png" alt="">
8676 * <dl>
8677 * <dt><b>Backpressure Support:</b></dt>
8678 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8679 * <dt><b>Scheduler:</b></dt>
8680 * <dd>{@code toMultiMap} does not operate by default on a particular {@link Scheduler}.</dd>
8681 * </dl>
8682 *
8683 * @param keySelector
8684 * the function that extracts the key from the source items to be used as key in the HashMap
8685 * @return an Observable that emits a single item: a HashMap that contains an ArrayList of items mapped from
8686 * the source Observable
8687 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8688 */
8689 public final <K> Observable<Map<K, Collection<T>>> toMultimap(Func1<? super T, ? extends K> keySelector) {
8690 return lift(new OperatorToMultimap<T, K, T>(keySelector, UtilityFunctions.<T>identity()));
8691 }
8692
8693 /**
8694 * Returns an Observable that emits a single HashMap that contains an ArrayList of values extracted by a
8695 * specified {@code valueSelector} function from items emitted by the source Observable, keyed by a
8696 * specified {@code keySelector} function.
8697 * <p>
8698 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.png" alt="">
8699 * <dl>
8700 * <dt><b>Backpressure Support:</b></dt>
8701 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8702 * <dt><b>Scheduler:</b></dt>
8703 * <dd>{@code toMultiMap} does not operate by default on a particular {@link Scheduler}.</dd>
8704 * </dl>
8705 *
8706 * @param keySelector
8707 * the function that extracts a key from the source items to be used as key in the HashMap
8708 * @param valueSelector
8709 * the function that extracts a value from the source items to be used as value in the HashMap
8710 * @return an Observable that emits a single item: a HashMap that contains an ArrayList of items mapped from
8711 * the source Observable
8712 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8713 */
8714 public final <K, V> Observable<Map<K, Collection<V>>> toMultimap(Func1<? super T, ? extends K> keySelector, Func1<? super T, ? extends V> valueSelector) {
8715 return lift(new OperatorToMultimap<T, K, V>(keySelector, valueSelector));
8716 }
8717
8718 /**
8719 * Returns an Observable that emits a single Map, returned by a specified {@code mapFactory} function, that
8720 * contains an ArrayList of values, extracted by a specified {@code valueSelector} function from items
8721 * emitted by the source Observable and keyed by the {@code keySelector} function.
8722 * <p>
8723 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.png" alt="">
8724 * <dl>
8725 * <dt><b>Backpressure Support:</b></dt>
8726 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8727 * <dt><b>Scheduler:</b></dt>
8728 * <dd>{@code toMultiMap} does not operate by default on a particular {@link Scheduler}.</dd>
8729 * </dl>
8730 *
8731 * @param keySelector
8732 * the function that extracts a key from the source items to be used as the key in the Map
8733 * @param valueSelector
8734 * the function that extracts a value from the source items to be used as the value in the Map
8735 * @param mapFactory
8736 * the function that returns a Map instance to be used
8737 * @return an Observable that emits a single item: a Map that contains a list items mapped from the source
8738 * Observable
8739 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8740 */
8741 public final <K, V> Observable<Map<K, Collection<V>>> toMultimap(Func1<? super T, ? extends K> keySelector, Func1<? super T, ? extends V> valueSelector, Func0<? extends Map<K, Collection<V>>> mapFactory) {
8742 return lift(new OperatorToMultimap<T, K, V>(keySelector, valueSelector, mapFactory));
8743 }
8744
8745 /**
8746 * Returns an Observable that emits a single Map, returned by a specified {@code mapFactory} function, that
8747 * contains a custom collection of values, extracted by a specified {@code valueSelector} function from
8748 * items emitted by the source Observable, and keyed by the {@code keySelector} function.
8749 * <p>
8750 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.png" alt="">
8751 * <dl>
8752 * <dt><b>Backpressure Support:</b></dt>
8753 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8754 * <dt><b>Scheduler:</b></dt>
8755 * <dd>{@code toMultiMap} does not operate by default on a particular {@link Scheduler}.</dd>
8756 * </dl>
8757 *
8758 * @param keySelector
8759 * the function that extracts a key from the source items to be used as the key in the Map
8760 * @param valueSelector
8761 * the function that extracts a value from the source items to be used as the value in the Map
8762 * @param mapFactory
8763 * the function that returns a Map instance to be used
8764 * @param collectionFactory
8765 * the function that returns a Collection instance for a particular key to be used in the Map
8766 * @return an Observable that emits a single item: a Map that contains the collection of mapped items from
8767 * the source Observable
8768 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8769 */
8770 public final <K, V> Observable<Map<K, Collection<V>>> toMultimap(Func1<? super T, ? extends K> keySelector, Func1<? super T, ? extends V> valueSelector, Func0<? extends Map<K, Collection<V>>> mapFactory, Func1<? super K, ? extends Collection<V>> collectionFactory) {
8771 return lift(new OperatorToMultimap<T, K, V>(keySelector, valueSelector, mapFactory, collectionFactory));
8772 }
8773
8774 /**
8775 * Returns an Observable that emits a list that contains the items emitted by the source Observable, in a
8776 * sorted order. Each item emitted by the Observable must implement {@link Comparable} with respect to all
8777 * other items in the sequence.
8778 * <p>
8779 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.png" alt="">
8780 * <dl>
8781 * <dt><b>Backpressure Support:</b></dt>
8782 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8783 * <dt><b>Scheduler:</b></dt>
8784 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
8785 * </dl>
8786 *
8787 * @throws ClassCastException
8788 * if any item emitted by the Observable does not implement {@link Comparable} with respect to
8789 * all other items emitted by the Observable
8790 * @return an Observable that emits a list that contains the items emitted by the source Observable in
8791 * sorted order
8792 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8793 */
8794 public final Observable<List<T>> toSortedList() {
8795 return lift(new OperatorToObservableSortedList<T>());
8796 }
8797
8798 /**
8799 * Returns an Observable that emits a list that contains the items emitted by the source Observable, in a
8800 * sorted order based on a specified comparison function.
8801 * <p>
8802 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.f.png" alt="">
8803 * <dl>
8804 * <dt><b>Backpressure Support:</b></dt>
8805 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
8806 * <dt><b>Scheduler:</b></dt>
8807 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
8808 * </dl>
8809 *
8810 * @param sortFunction
8811 * a function that compares two items emitted by the source Observable and returns an Integer
8812 * that indicates their sort order
8813 * @return an Observable that emits a list that contains the items emitted by the source Observable in
8814 * sorted order
8815 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
8816 */
8817 public final Observable<List<T>> toSortedList(Func2<? super T, ? super T, Integer> sortFunction) {
8818 return lift(new OperatorToObservableSortedList<T>(sortFunction));
8819 }
8820
8821 /**
8822 * Modifies the source Observable so that subscribers will unsubscribe from it on a specified
8823 * {@link Scheduler}.
8824 * <dl>
8825 * <dt><b>Scheduler:</b></dt>
8826 * <dd>you specify which {@link Scheduler} this operator will use</dd>
8827 * </dl>
8828 *
8829 * @param scheduler
8830 * the {@link Scheduler} to perform unsubscription actions on
8831 * @return the source Observable modified so that its unsubscriptions happen on the specified
8832 * {@link Scheduler}
8833 * @see <a href="http://reactivex.io/documentation/operators/subscribeon.html">ReactiveX operators documentation: SubscribeOn</a>
8834 */
8835 public final Observable<T> unsubscribeOn(Scheduler scheduler) {
8836 return lift(new OperatorUnsubscribeOn<T>(scheduler));
8837 }
8838
8839 /**
8840 * Merges the specified Observable into this Observable sequence by using the {@code resultSelector}
8841 * function only when the source Observable (this instance) emits an item.
8842 * <p>
8843 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/withLatestFrom.png" alt="">
8844 *
8845 * @warn "Backpressure Support" section missing from javadoc
8846 * @warn "Scheduler" section missing from javadoc
8847 * @param other
8848 * the other Observable
8849 * @param resultSelector
8850 * the function to call when this Observable emits an item and the other Observable has already
8851 * emitted an item, to generate the item to be emitted by the resulting Observable
8852 * @return an Observable that merges the specified Observable into this Observable by using the
8853 * {@code resultSelector} function only when the source Observable sequence (this instance) emits an
8854 * item
8855 * @Experimental The behavior of this can change at any time.
8856 * @since (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
8857 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
8858 */
8859 @Experimental
8860 public final <U, R> Observable<R> withLatestFrom(Observable<? extends U> other, Func2<? super T, ? super U, ? extends R> resultSelector) {
8861 return lift(new OperatorWithLatestFrom<T, U, R>(other, resultSelector));
8862 }
8863
8864 /**
8865 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
8866 * Observable emits connected, non-overlapping windows. It emits the current window and opens a new one
8867 * whenever the Observable produced by the specified {@code closingSelector} emits an item.
8868 * <p>
8869 * <img width="640" height="485" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window1.png" alt="">
8870 * <dl>
8871 * <dt><b>Backpressure Support:</b></dt>
8872 * <dd>This operator does not support backpressure as it uses the {@code closingSelector} to control data
8873 * flow.</dd>
8874 * <dt><b>Scheduler:</b></dt>
8875 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
8876 * </dl>
8877 *
8878 * @param closingSelector
8879 * a {@link Func0} that returns an {@code Observable} that governs the boundary between windows.
8880 * When this {@code Observable} emits an item, {@code window} emits the current window and begins
8881 * a new one.
8882 * @return an Observable that emits connected, non-overlapping windows of items from the source Observable
8883 * whenever {@code closingSelector} emits an item
8884 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
8885 */
8886 public final <TClosing> Observable<Observable<T>> window(Func0<? extends Observable<? extends TClosing>> closingSelector) {
8887 return lift(new OperatorWindowWithObservable<T, TClosing>(closingSelector));
8888 }
8889
8890 /**
8891 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
8892 * Observable emits connected, non-overlapping windows, each containing {@code count} items. When the source
8893 * Observable completes or encounters an error, the resulting Observable emits the current window and
8894 * propagates the notification from the source Observable.
8895 * <p>
8896 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window3.png" alt="">
8897 * <dl>
8898 * <dt><b>Backpressure Support:</b></dt>
8899 * <dd>This operator does not support backpressure as it uses {@code count} to control data flow.</dd>
8900 * <dt><b>Scheduler:</b></dt>
8901 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
8902 * </dl>
8903 *
8904 * @param count
8905 * the maximum size of each window before it should be emitted
8906 * @return an Observable that emits connected, non-overlapping windows, each containing at most
8907 * {@code count} items from the source Observable
8908 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
8909 */
8910 public final Observable<Observable<T>> window(int count) {
8911 return window(count, count);
8912 }
8913
8914 /**
8915 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
8916 * Observable emits windows every {@code skip} items, each containing no more than {@code count} items. When
8917 * the source Observable completes or encounters an error, the resulting Observable emits the current window
8918 * and propagates the notification from the source Observable.
8919 * <p>
8920 * <img width="640" height="365" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window4.png" alt="">
8921 * <dl>
8922 * <dt><b>Backpressure Support:</b></dt>
8923 * <dd>This operator does not support backpressure as it uses {@code count} to control data flow.</dd>
8924 * <dt><b>Scheduler:</b></dt>
8925 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
8926 * </dl>
8927 *
8928 * @param count
8929 * the maximum size of each window before it should be emitted
8930 * @param skip
8931 * how many items need to be skipped before starting a new window. Note that if {@code skip} and
8932 * {@code count} are equal this is the same operation as {@link #window(int)}.
8933 * @return an Observable that emits windows every {@code skip} items containing at most {@code count} items
8934 * from the source Observable
8935 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
8936 */
8937 public final Observable<Observable<T>> window(int count, int skip) {
8938 return lift(new OperatorWindowWithSize<T>(count, skip));
8939 }
8940
8941 /**
8942 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
8943 * Observable starts a new window periodically, as determined by the {@code timeshift} argument. It emits
8944 * each window after a fixed timespan, specified by the {@code timespan} argument. When the source
8945 * Observable completes or Observable completes or encounters an error, the resulting Observable emits the
8946 * current window and propagates the notification from the source Observable.
8947 * <p>
8948 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window7.png" alt="">
8949 * <dl>
8950 * <dt><b>Backpressure Support:</b></dt>
8951 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8952 * <dt><b>Scheduler:</b></dt>
8953 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
8954 * </dl>
8955 *
8956 * @param timespan
8957 * the period of time each window collects items before it should be emitted
8958 * @param timeshift
8959 * the period of time after which a new window will be created
8960 * @param unit
8961 * the unit of time that applies to the {@code timespan} and {@code timeshift} arguments
8962 * @return an Observable that emits new windows periodically as a fixed timespan elapses
8963 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
8964 */
8965 public final Observable<Observable<T>> window(long timespan, long timeshift, TimeUnit unit) {
8966 return window(timespan, timeshift, unit, Integer.MAX_VALUE, Schedulers.computation());
8967 }
8968
8969 /**
8970 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
8971 * Observable starts a new window periodically, as determined by the {@code timeshift} argument. It emits
8972 * each window after a fixed timespan, specified by the {@code timespan} argument. When the source
8973 * Observable completes or Observable completes or encounters an error, the resulting Observable emits the
8974 * current window and propagates the notification from the source Observable.
8975 * <p>
8976 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window7.s.png" alt="">
8977 * <dl>
8978 * <dt><b>Backpressure Support:</b></dt>
8979 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8980 * <dt><b>Scheduler:</b></dt>
8981 * <dd>you specify which {@link Scheduler} this operator will use</dd>
8982 * </dl>
8983 *
8984 * @param timespan
8985 * the period of time each window collects items before it should be emitted
8986 * @param timeshift
8987 * the period of time after which a new window will be created
8988 * @param unit
8989 * the unit of time that applies to the {@code timespan} and {@code timeshift} arguments
8990 * @param scheduler
8991 * the {@link Scheduler} to use when determining the end and start of a window
8992 * @return an Observable that emits new windows periodically as a fixed timespan elapses
8993 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
8994 */
8995 public final Observable<Observable<T>> window(long timespan, long timeshift, TimeUnit unit, Scheduler scheduler) {
8996 return window(timespan, timeshift, unit, Integer.MAX_VALUE, scheduler);
8997 }
8998
8999 /**
9000 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
9001 * Observable starts a new window periodically, as determined by the {@code timeshift} argument or a maximum
9002 * size as specified by the {@code count} argument (whichever is reached first). It emits
9003 * each window after a fixed timespan, specified by the {@code timespan} argument. When the source
9004 * Observable completes or Observable completes or encounters an error, the resulting Observable emits the
9005 * current window and propagates the notification from the source Observable.
9006 * <p>
9007 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window7.s.png" alt="">
9008 * <dl>
9009 * <dt><b>Backpressure Support:</b></dt>
9010 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
9011 * <dt><b>Scheduler:</b></dt>
9012 * <dd>you specify which {@link Scheduler} this operator will use</dd>
9013 * </dl>
9014 *
9015 * @param timespan
9016 * the period of time each window collects items before it should be emitted
9017 * @param timeshift
9018 * the period of time after which a new window will be created
9019 * @param unit
9020 * the unit of time that applies to the {@code timespan} and {@code timeshift} arguments
9021 * @param count
9022 * the maximum size of each window before it should be emitted
9023 * @param scheduler
9024 * the {@link Scheduler} to use when determining the end and start of a window
9025 * @return an Observable that emits new windows periodically as a fixed timespan elapses
9026 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
9027 */
9028 public final Observable<Observable<T>> window(long timespan, long timeshift, TimeUnit unit, int count, Scheduler scheduler) {
9029 return lift(new OperatorWindowWithTime<T>(timespan, timeshift, unit, count, scheduler));
9030 }
9031
9032 /**
9033 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
9034 * Observable emits connected, non-overlapping windows, each of a fixed duration specified by the
9035 * {@code timespan} argument. When the source Observable completes or encounters an error, the resulting
9036 * Observable emits the current window and propagates the notification from the source Observable.
9037 * <p>
9038 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window5.png" alt="">
9039 * <dl>
9040 * <dt><b>Backpressure Support:</b></dt>
9041 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
9042 * <dt><b>Scheduler:</b></dt>
9043 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
9044 * </dl>
9045 *
9046 * @param timespan
9047 * the period of time each window collects items before it should be emitted and replaced with a
9048 * new window
9049 * @param unit
9050 * the unit of time that applies to the {@code timespan} argument
9051 * @return an Observable that emits connected, non-overlapping windows represending items emitted by the
9052 * source Observable during fixed, consecutive durations
9053 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
9054 */
9055 public final Observable<Observable<T>> window(long timespan, TimeUnit unit) {
9056 return window(timespan, timespan, unit, Schedulers.computation());
9057 }
9058
9059 /**
9060 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
9061 * Observable emits connected, non-overlapping windows, each of a fixed duration as specified by the
9062 * {@code timespan} argument or a maximum size as specified by the {@code count} argument (whichever is
9063 * reached first). When the source Observable completes or encounters an error, the resulting Observable
9064 * emits the current window and propagates the notification from the source Observable.
9065 * <p>
9066 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.png" alt="">
9067 * <dl>
9068 * <dt><b>Backpressure Support:</b></dt>
9069 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
9070 * <dt><b>Scheduler:</b></dt>
9071 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
9072 * </dl>
9073 *
9074 * @param timespan
9075 * the period of time each window collects items before it should be emitted and replaced with a
9076 * new window
9077 * @param unit
9078 * the unit of time that applies to the {@code timespan} argument
9079 * @param count
9080 * the maximum size of each window before it should be emitted
9081 * @return an Observable that emits connected, non-overlapping windows of items from the source Observable
9082 * that were emitted during a fixed duration of time or when the window has reached maximum capacity
9083 * (whichever occurs first)
9084 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
9085 */
9086 public final Observable<Observable<T>> window(long timespan, TimeUnit unit, int count) {
9087 return window(timespan, unit, count, Schedulers.computation());
9088 }
9089
9090 /**
9091 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
9092 * Observable emits connected, non-overlapping windows, each of a fixed duration specified by the
9093 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
9094 * first). When the source Observable completes or encounters an error, the resulting Observable emits the
9095 * current window and propagates the notification from the source Observable.
9096 * <p>
9097 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.s.png" alt="">
9098 * <dl>
9099 * <dt><b>Backpressure Support:</b></dt>
9100 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
9101 * <dt><b>Scheduler:</b></dt>
9102 * <dd>you specify which {@link Scheduler} this operator will use</dd>
9103 * </dl>
9104 *
9105 * @param timespan
9106 * the period of time each window collects items before it should be emitted and replaced with a
9107 * new window
9108 * @param unit
9109 * the unit of time which applies to the {@code timespan} argument
9110 * @param count
9111 * the maximum size of each window before it should be emitted
9112 * @param scheduler
9113 * the {@link Scheduler} to use when determining the end and start of a window
9114 * @return an Observable that emits connected, non-overlapping windows of items from the source Observable
9115 * that were emitted during a fixed duration of time or when the window has reached maximum capacity
9116 * (whichever occurs first)
9117 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
9118 */
9119 public final Observable<Observable<T>> window(long timespan, TimeUnit unit, int count, Scheduler scheduler) {
9120 return window(timespan, timespan, unit, count, scheduler);
9121 }
9122
9123 /**
9124 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
9125 * Observable emits connected, non-overlapping windows, each of a fixed duration as specified by the
9126 * {@code timespan} argument. When the source Observable completes or encounters an error, the resulting
9127 * Observable emits the current window and propagates the notification from the source Observable.
9128 * <p>
9129 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window5.s.png" alt="">
9130 * <dl>
9131 * <dt><b>Backpressure Support:</b></dt>
9132 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
9133 * <dt><b>Scheduler:</b></dt>
9134 * <dd>you specify which {@link Scheduler} this operator will use</dd>
9135 * </dl>
9136 *
9137 * @param timespan
9138 * the period of time each window collects items before it should be emitted and replaced with a
9139 * new window
9140 * @param unit
9141 * the unit of time which applies to the {@code timespan} argument
9142 * @param scheduler
9143 * the {@link Scheduler} to use when determining the end and start of a window
9144 * @return an Observable that emits connected, non-overlapping windows containing items emitted by the
9145 * source Observable within a fixed duration
9146 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
9147 */
9148 public final Observable<Observable<T>> window(long timespan, TimeUnit unit, Scheduler scheduler) {
9149 return window(timespan, unit, Integer.MAX_VALUE, scheduler);
9150 }
9151
9152 /**
9153 * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
9154 * Observable emits windows that contain those items emitted by the source Observable between the time when
9155 * the {@code windowOpenings} Observable emits an item and when the Observable returned by
9156 * {@code closingSelector} emits an item.
9157 * <p>
9158 * <img width="640" height="550" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window2.png" alt="">
9159 * <dl>
9160 * <dt><b>Backpressure Support:</b></dt>
9161 * <dd>This operator does not support backpressure as it uses Observables to control data flow.</dd>
9162 * <dt><b>Scheduler:</b></dt>
9163 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
9164 * </dl>
9165 *
9166 * @param windowOpenings
9167 * an Observable that, when it emits an item, causes another window to be created
9168 * @param closingSelector
9169 * a {@link Func1} that produces an Observable for every window created. When this Observable
9170 * emits an item, the associated window is closed and emitted
9171 * @return an Observable that emits windows of items emitted by the source Observable that are governed by
9172 * the specified window-governing Observables
9173 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
9174 */
9175 public final <TOpening, TClosing> Observable<Observable<T>> window(Observable<? extends TOpening> windowOpenings, Func1<? super TOpening, ? extends Observable<? extends TClosing>> closingSelector) {
9176 return lift(new OperatorWindowWithStartEndObservable<T, TOpening, TClosing>(windowOpenings, closingSelector));
9177 }
9178
9179 /**
9180 * Returns an Observable that emits non-overlapping windows of items it collects from the source Observable
9181 * where the boundary of each window is determined by the items emitted from a specified boundary-governing
9182 * Observable.
9183 * <p>
9184 * <img width="640" height="475" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window8.png" alt="">
9185 * <dl>
9186 * <dt><b>Backpressure Support:</b></dt>
9187 * <dd>This operator does not support backpressure as it uses a {@code boundary} Observable to control data
9188 * flow.</dd>
9189 * <dt><b>Scheduler:</b></dt>
9190 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
9191 * </dl>
9192 *
9193 * @param <U>
9194 * the window element type (ignored)
9195 * @param boundary
9196 * an Observable whose emitted items close and open windows
9197 * @return an Observable that emits non-overlapping windows of items it collects from the source Observable
9198 * where the boundary of each window is determined by the items emitted from the {@code boundary}
9199 * Observable
9200 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
9201 */
9202 public final <U> Observable<Observable<T>> window(Observable<U> boundary) {
9203 return lift(new OperatorWindowWithObservable<T, U>(boundary));
9204 }
9205
9206 /**
9207 * Returns an Observable that emits items that are the result of applying a specified function to pairs of
9208 * values, one each from the source Observable and a specified Iterable sequence.
9209 * <p>
9210 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.i.png" alt="">
9211 * <p>
9212 * Note that the {@code other} Iterable is evaluated as items are observed from the source Observable; it is
9213 * not pre-consumed. This allows you to zip infinite streams on either side.
9214 * <dl>
9215 * <dt><b>Scheduler:</b></dt>
9216 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
9217 * </dl>
9218 *
9219 * @param <T2>
9220 * the type of items in the {@code other} Iterable
9221 * @param <R>
9222 * the type of items emitted by the resulting Observable
9223 * @param other
9224 * the Iterable sequence
9225 * @param zipFunction
9226 * a function that combines the pairs of items from the Observable and the Iterable to generate
9227 * the items to be emitted by the resulting Observable
9228 * @return an Observable that pairs up values from the source Observable and the {@code other} Iterable
9229 * sequence and emits the results of {@code zipFunction} applied to these pairs
9230 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
9231 */
9232 public final <T2, R> Observable<R> zipWith(Iterable<? extends T2> other, Func2<? super T, ? super T2, ? extends R> zipFunction) {
9233 return lift(new OperatorZipIterable<T, T2, R>(other, zipFunction));
9234 }
9235
9236 /**
9237 * Returns an Observable that emits items that are the result of applying a specified function to pairs of
9238 * values, one each from the source Observable and another specified Observable.
9239 * <p>
9240 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.png" alt="">
9241 * <dl>
9242 * <dt><b>Scheduler:</b></dt>
9243 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
9244 * </dl>
9245 *
9246 * @param <T2>
9247 * the type of items emitted by the {@code other} Observable
9248 * @param <R>
9249 * the type of items emitted by the resulting Observable
9250 * @param other
9251 * the other Observable
9252 * @param zipFunction
9253 * a function that combines the pairs of items from the two Observables to generate the items to
9254 * be emitted by the resulting Observable
9255 * @return an Observable that pairs up values from the source Observable and the {@code other} Observable
9256 * and emits the results of {@code zipFunction} applied to these pairs
9257 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
9258 */
9259 public final <T2, R> Observable<R> zipWith(Observable<? extends T2> other, Func2<? super T, ? super T2, ? extends R> zipFunction) {
9260 return zip(this, other, zipFunction);
9261 }
9262
9263 /**
9264 * An Observable that never sends any information to an {@link Observer}.
9265 * This Observable is useful primarily for testing purposes.
9266 *
9267 * @param <T>
9268 * the type of item (not) emitted by the Observable
9269 */
9270 private static class NeverObservable<T> extends Observable<T> {
9271 public NeverObservable() {
9272 super(new OnSubscribe<T>() {
9273
9274 @Override
9275 public void call(Subscriber<? super T> observer) {
9276 // do nothing
9277 }
9278
9279 });
9280 }
9281 }
9282
9283 /**
9284 * An Observable that invokes {@link Observer#onError onError} when the {@link Observer} subscribes to it.
9285 *
9286 * @param <T>
9287 * the type of item (ostensibly) emitted by the Observable
9288 */
9289 private static class ThrowObservable<T> extends Observable<T> {
9290
9291 public ThrowObservable(final Throwable exception) {
9292 super(new OnSubscribe<T>() {
9293
9294 /**
9295 * Accepts an {@link Observer} and calls its {@link Observer#onError onError} method.
9296 *
9297 * @param observer
9298 * an {@link Observer} of this Observable
9299 */
9300 @Override
9301 public void call(Subscriber<? super T> observer) {
9302 observer.onError(exception);
9303 }
9304
9305 });
9306 }
9307 }
9308
9309 }